construction 

engineering 

research 

laboratory 


United  States  Army 
Corps  of  Engineers 

...Serving  the  Army 
...Serving  the  Nation  ^ 


TECHNICAL  REPORT  E-147 
February  1979 


THE  AUTOMATED  DOCUMENTATION 
SYSTEM-USER  MANUAL 


Linda  Lawrie 


Approved  for  public  release;  distribution  unlimited 


The  contents  of  this  report  are  not  to  be  used  tor  advertising,  publication,  or 
promotional  purposes.  Citation  of  trade  names  does  not  constitute  an 
official  indorsement  or  approval  of  the  use  of  such  commercial  products 
The  findings  of  this  report  are  not  to  be  construed  as  an  official  Department 
of  the  Army  position,  unless  so  designated  by  other  authorized  documents. 


DESTROY  THIS  REPORT  WHEN  IT  IS  NO  LONGER  NEEDED 
DO  NOT  RETURN  IT  TO  THE  ORIGIN  A TOR 


SECURITY  CLASSIFICATION  OF  THIS  PAGE  (When  Dmtm  Entered) 

REPORT  DOCUMENTATION  PAGE  befor^comple^form 

A.  REPORT  NUMBER  |2.  GOVT  ACCESSION  NO.  3-  RECIPIENT’S  CATALOG  NUMBER 


1 REPORT  NUMBER 

) CERL-TR-E-147/ 

4.  TITLE  (end  Subtitle) 


I THE  AUTOMATED  DOCUMENTATION  SYSTEM— USER  MANUAL.  j/TINAL  .. 


PERIOD  COVERED 


6.  PERFORMING  ORG.  REPORT  NUMBER 


I ,,  f AUTHOWiT _ ' 

/ -•  ' Linda/Lawrie 


8.  CONTRACT  OR  GRANT  NUMBERfi) 


19.  PERFORMING  ORGANIZATION  NAME  AND  ADDRESS 


/ — 10.  PROGRAM  ELEMENT,  PROJECT,  TASK 

AREA  & WORK  UNIT  NUMBERS 


u-s-  A^rny  {/&*■ i ft'  j 7 — 

CONSTRUCTION  ENGINEERING  RESEARCH  LABORATORY  S- **  4A762725AT1  li-02  JjJ  l * 
P.0.  Box  4005,  Champaign,  IL  61820 1 ~ ~ 

It.  CONTROLLING  OFFICE  NAME  AND  ADDRESS  12. . REPORT-OATe 

ll  J February  1979 

' — ^ nr.  “HUMBER'or  ^G  ES 

84 

u.  MONITORING  AGENCY  NAME  & ADDRESS</(  dltl*rw,t  from  Controlling  Otllct)  15.  SECURITY  CLASS,  (o  1 Ihl*  report) 


Unclassified 


ts«.  declassification/downgraoing 
SCHEDULE 


16.  DISTRIBUTION  STATEMENT  (of  thia  Report) 

Approved  for  public  release;  distribution  unlimited. 


17.  DISTRIBUTION  STATEMENT  (of  the  abatrmct  an tered  In  Block  20,  If  different  from  Report) 


18.  SUPPLEMENTARY  NOTES 

Copies  are  obtainable  from  National  Technical  Information  Service 

Springfield,  VA  22151 

19-  KEY  WORDS  (Continue  on  rereram  aide  It  nacaaamry  and  Identify  by  block  number) 

software  development 
FORTRAN 

computer  documentation 


28.  ABSTRACT  (Caottoue  ate  rereram  at+e  M neeemeary  mod  Identify  by  block  number) 

MThe  Automated  Documentation  System  (ADS)  is  a computer  program  and 
user  procedure  designed  to  facilitate  management  of  the  development  of 
software  and  the  production  of  final  documentation  for  FORTRAN  programs. 
The  ADS  system  can  be  used  in  two  ways. 

(1)  At  any  point  during  development  of  the  software,  the  status  of 
the  development  process  can  be  determined  by  application  of  the  program 


DO  1473 


EDITION  OF  I NOV  «S  IS  OBSOLETE 

VOS  2 7 / 


UNCLASSIFIED 

SECURITY  CLASSIFICATION  OF  THIS  P AGE  (Nfc»n  D«l»  Enler.d) 


Block  20  continued. 


^to  the  source  code  under  development.  Flow  charts  and  internal  documen- 
tation are  summarized  for  the  program  manager. 

(2)  After  the  software  is  complete,  external  documentation  can  be 
produced  from  the  internal  documentation  and  compilation  maps  by  running 
the  AOS  program. 

The  ADS  program  is  written  in  Control  Data  Corporation  (CDC)  FOR- 
TRAN extended,  version  4.6  and  can  be  used  on  CDC  6000/7000  series  com- 
puters with  few  or  no  modifications.  This  report  provides  detailed  user 
instructions  for  ADS.^ 


_r_-  4. 


UNCLASSIFIED 


SECURITY  CLASSIFICATION  OF  THIS  P AGEflFhen  Data  Entered) 


FOREWORD 


This  research  was  conducted  by  the  Energy  and  Habitability  Division 
(EH)  of  the  U.S.  Army  Construction  Engineering  Research  Laboratory 
(CERL)  for  the  Engineering  and  Scientific  Division  of  the  Engineering 
and  Data  Systems  Office,  Department  of  the  Army,  under  RDT&E  Program 
6.27.25A,  Project  4A762725AT11 , "Engineering  Software  Development,"  Task 
02,  "Comprehensive  Standard  for  Software  Development." 

Mr.  Gene  Manning  was  the  Technical  Monitor.  Mr.  Douglas  C.  Hittle 
was  the  CERL  principal  investigator.  Administrative  support  was  pro- 
vided by  Dr.  D.  J.  Leverenz  and  Mr.  R.  G.  Donaghy,  Chief  of  EH. 

The  ADS  program  was  authored  by  Ms.  L.  Lawrie,  Mr.  R.  Lidral , Mr. 

D.  Herron,  Mr.  K.  Morgan,  Mr.  A.  Itzkowitz,  and  Mr.  D.  Burn;  background 
to  the  ADS  system  was  provided  by  Mr.  W.  Struebing.  Appreciation  is  ex- 
pressed to  M.  L.  Scala  for  her  help  in  writing  this  report. 

COL  J.  E.  Hays  is  Commander  and  Director  of  CERL,  and  Dr.  L.  R. 
Shaffer  is  Technical  Director. 


CONTENTS 


Page 


DD  FORM  1473  1 

FOREWORD  3 

LIST  OF  TABLES  AND  FIGURES  5 

1 INTRODUCTION.. 7 

Objective 

Outl ine  of  Report 

Mode  of  Technology  Transfer 

2 ADS  REPORT 9 

Background 


Beginning  the  Documentation  Process  With  ADS 
Expanding  and  Updating  Documentation 
Documentation  Output 
Exampl e 


3 ADS  SOURCE  CODE  INPUT  - FORMAT 20 

Common  Block  Input 
Variable  Dictionary  Input 

4 ADS  PROGRAM  CONTROL  AND  OPTIONS 25 


External  Reports:  Filing  and  Retrieval 

Additional  ADS  Documentation  Output 

Delete  Option 

Print  Option 

Tree  Option 

Other  Options 


5  ADS  JOB  CONTROL 31 

APPENDIX  A:  ADS  Documentation  Category  and  Usage  Guide  34 
APPENDIX  B:  ADS  User  Error  Messages  38 
APPENDIX  C:  Quick  Reference  — ADS  User  and  Code  Input  44 
APPENDIX  D:  ADS  REFFL  Input  File  Example  47 
APPENDIX  E:  ADS  Execution  Example  64 


DISTRIBUTION 


i 


4 


k A « 


TABLE 


Number  Pagp 

I ADS  Documentation  Categories  21 

FIGURES 

1 ADS  Input  and  Output  10 

2 Expansion  and  Update  of  ADS  Documentat ion  14 

3 Production  of  Reports  Directly  From  Documentation  Files  14 

4 FORTRAN  Source  Code  for  a Main  Program  15 

5 Complier  Reference  Map  for  Program  in  Figure  4 16 

6 Sample  ADS  Commands  17 

7 Sample  ADS  Report  17 

8 Sample  of  Source  Code  for  a Subroutine  18 

9 Sample  of  Reference  Map  for  a Subroutine  18 

10  Sample  ADS  Commands  to  Update  Documentation  by  19 

Adding  Subroutine 

II  Sample  ADS  Commands  Used  Only  for  Production  of  External  19 

Documentation  Reports 

12  Tree  Diagram  of  Program  Under  Development  19 

13  FORTRAN  Source  Code  Implanted  With  ADS  Comments  23 

14  ADS  Output  From  Figure  13  23 

15  ADS  Command  Example  33 


THE  AUTOMATED  DOCUMENTATION 
SYSTEM  — USER  MANUAL 


1 INTRODUCTION 


Good  documentation  can  appreciably  extend  the  useful  life  of  a 
software  tool  and  increase  its  efficiency  by  allowing  individuals  not 
involved  in  its  initial  development  to  use  it  effectively.  There  are, 
however,  no  universal  standards  for  good  documentation.  Indeed,  what  is 
effective  documentation  for  one  type  of  software  may  be  completely  in- 
sufficient to  the  needs  of  another  type  of  software.  In  addition,  pro- 
grammers are  generally  unable  or  unwilling  to  prepare  documentation 
until  after  completion  of  the  final  development  of  software  tools  -- 
long  after  details  intrinsic  to  the  development  process  are  forgotten. 

As  a result,  it  is  almost  impossible  for  software  managers  to  obtain  ac- 
curate, up-to-date  reports  on  the  ongoing  development  process. 

The  Automated  Documentation  System  (ADS)  was  developed  to  provide 
high-quality  documentation  while  simplifying  the  jobs  of  both  the  pro- 
gram developer  and  the  software  manager.  In  effect,  ADS  becomes  part  of 
the  software  tool,  thereby  allowing  internal  and  external  documentation 
to  proceed  simul taneously  with  software  development.  ADS  can  create 
documentation  tailored  to  the  unique  needs  of  a software  tool,  relieve 
programmers  of  the  tedious  task  of  "after-the-fact"  documentation,  and 
provide  software  managers  with  an  effective  method  of  supervising  the 
software  development  process. 


■ 


Objecti ve 


The  overall  objective  of  this  study  was  to  provide  a comprehensive 
standard  for  software  development,  and  to  provide  user  instructions  for 
the  ADS  method  of  producing  internal  and  external  documentation  for 
software  projects. 


Outline  of  Report 


Chapter  2 contains  an  overview  of  ADS;  Chapter  3 describes  ADS 
input  format  code;  Chapter  4 details  ADS  program  control,  ADS  commands, 
and  various  options  available  with  ADS;  and  Chapter  5 outlines  ADS  job 
control  and  data  files  used  by  ADS. 


RECEDING  PAGE  BLANK. NOT  FILLED 


2 ADS  OVERVIEW 


Background 

Essentially,  ADS  is  an  organizational  tool  --  a program  for  report- 
ing on  the  development  of  another  program.  Its  function  is  that  of  the 
journal ist/1 ibrarian  of  a program  under  development:  first,  it  gathers 
information  supplied  to  it  by  the  programmer  and  computer;  it  then 
files,  organizes,  and  cross-references  this  information.  Finally,  it 
summarizes  the  information  in  a report. 

At  present,  ADS  can  only  be  used  to  document  FORTRAN  programs,  and 
will  only  interface  with  compiler  reference  maps  produced  by  the  Control 
Data  Corporation  (CDC). 

This  chapter  presents  an  overview  of  ADS  --  how  it  works  and  how  it 
can  be  manipulated  by  the  user.  Although  ADS  is  itself  a program,  to 
avoid  confusion  the  terms  "program,”  "subprogram,"  "routine,"  "source 
code,"  etc.,  will  refer  only  to  the  program  under  development  and  bring 
documented  by  ADS. 

Using  ADS  on  a program  under  development  is  easy.  The  basic  re- 
quirement is  that  ADS  comment  cards  be  implanted  in  the  FORTRAN  source 
code  of  the  program  being  documented  by  ADS.  Thus,  ADS  allows  documen- 
tation to  proceed  simul taneously  with  software  development. 


Beginning  the  Documentation  Process  With  ADS 

ADS  initially  requires  three  types  of  input  (see  Figure  1): 

1.  All  or  part  of  the  source  code  implanted  with  ADS  comment  cards 

2.  ADS  commands 

3.  The  compiler  reference  map  for  all  or  part  of  the  program  under 
devel opment . 


The  source  code  is  the  actual  FORTRAN  code  of  the  program  being  documen- 
ted by  ADS;  ADS  can  use  all  or  part  of  this  code.  ADS  commands  are  user 
instructions  to  ADS  which  tell  ADS  what  to  do  with  other  inputs  and  what 
reports  to  produce. 


The  third  ADS  input,  the  compiler  reference  map,  is 
output  produced  by  the  FORTRAN  compiler  on  CDC  computers 
follows  the  FORTRAN  source  code  listing  also  produced  by 
The  compiler  reference  map  is  used  by  ADS  because  it  is. 


part  of  t ho 
and  usually 
the  compiler, 
in  effect,  an 
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Figure  1.  ADS  input  and  output. 
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index  of  the  program  (subroutine,  common  block)  under  development.  It 
includes  information  pertinent  to  the  program,  such  as: 

1.  Variable  names 

2.  Routines  called  within  the  program  or  subprogram 

3.  Common  blocks  referenced  within  the  program  or  subprogram 

4.  Entry  points  for  the  program  or  subprogram 

5.  Files  referenced  by  the  program  or  subprogram 

6.  Inline  functions  used  by  the  program  or  subprogram 

7.  Equivalence  classes  for  variables 

8.  The  length  of  the  program,  subprogram,  common  blocks,  arrays, 

etc. 


(Note:  FORTRAN  programs  or  subroutines  must  be  compiled  [with  or 
without  errors]  before  ADS  can  be  used  to  document  them.) 

The  compiler  reference  map  not  only  provides  information  useful  for 
the  documentation  of  the  source  code  of  the  program  under  development, 
but  provides  a means  by  which  ADS  can  verify  the  comprehensiveness  and 
accuracy  of  the  ADS  comment  cards  implanted  in  the  program  source  code 
by  the  user. 

ADS  produces  two  types  of  output  from  the  input  described  above: 

1.  External  documentation  reports 

2.  Internal  documentation  files. 

External  documentation  reports  are  the  program  documentation  produced  by 
ADS;  their  content  depends  upon  the  commands  given  ADS  by  the  user. 

These  commands  are  detailed  in  Chapter  4.  Documentation  files  are 
stored  computer  files  and  contain  data  regarding  the  program  under  de- 
velopment that  is  being  documented  by  ADS.  These  data  are  derived  from 
ADS  comment  cards  and  the  compiler  reference  map.  Since  documentation 
files  are  stored  online  in  the  computer,  they  can  be  retained  indefi- 
nitely and  used  to  create  reports  and/or  new  documentation  files  as  the 
program  is  refined  and  extended.  The  only  requirement  of  the  pro- 
grammers is  that  they  exercise  ADS  frequently  enough  to  keep  the  docu- 
mentation files  current  with  the  software  development  activity. 
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Expanding  and  Updating  Documentation 


ADS  is  intended  for  use  during  the  initial  as  well  as  intermediate 
and  final  stages  of  software  development.  Since  ADS  is  designed  to 
update  and  expand  its  documentation,  it  can  be  implemented  even  in  the 
"skeletal"  phase  of  program  development,  i.e.,  when  a program  consists 
of  routines  yet  to  be  fully  developed,  routines  which  though  largely  de- 
veloped will  require  revision,  as  well  as  routines  in  final  form. 

Updates  and  expansion  of  APS  documentation  do  not  require  the  programmer 
to  redo  documentation  input  for  software  elements  that  do  not  change . 


When  in  the  update  mode,  ADS  uses  the  source  code  and  compiler  ref- 
erence map  for  new  and  revised  portions  of  the  program  under  devel- 
opment, as  well  as  information  from  the  documentation  files  pertaining 
to  software  elements  which  do  not  change.  The  source  code,  reference 
map,  and  "old"  documentation  files  are  input  to  ADS  to  produce  new  docu- 
mentation files  and/or  new  external  documentation  reports. 


This  process  should  be  repeated  as  often  as  necessary  to  assure  up- 
to-date  documentation  of  the  program.  The  process  is  usually  inexpen- 
sive since  data  relating  to  unchanged  software  elements  can  pass  without 
manipulation  from  old  to  new  ADS  documentation  files.  The  user  and  ADS 
need  only  process  data  relating  to  new  or  revised  portions  of  the  pro- 
gram such  as  new  subroutines,  changed  common  blocks,  etc.  (See  Figure 
2.) 


Documentation  Output 


External  documentation  reports  for  the  program  under  development 
can  be  produced  by  running  ADS  using  the  documentation  files  without 
referring  to  either  the  source  code  or  the  compiler  reference  map  (see 
Figure  3).  The  most  recent  documentation  files  are  used  by  ADS  to  pro- 
duce the  report  in  the  form  dictated  to  it  by  the  user  in  the  ADS  com- 
mands. This  option  of  retrieving  documentation  from  ADS  at  any  time  is 
especially  useful  to  software  project  managers  and  team  leaders  because 
it  allows  them  to  monitor  the  progress  of  a software  development  project 
without  disturbing  the  program  developers. 


Exampl e 


Figures  4,  5,  and  6 show  the  FORTRAN  source  code  for  a main  pro- 
gram, the  compiler  reference  map  for  that  program,  and  the  ADS  commands 
which  will  activate  the  ADS  documentation  files  and  write  external  re- 
ports, respectively.  Figure  7 is  a sample  of  a report  produced  by  ADS. 
Figures  3,  9,  and  10  are  the  source  code,  reference  map,  and  ADS  com- 
mands, respectively,  necessary  to  update  documentation  by  adding  one 
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subroutine.  Figure  11  is  the  ADS  commands  which  are  used  only  for  pro- 
ducing external  documentation  reports.  Finally,  Figure  12  is  a sample 
of  a second  external  documentation  report  option  available  from  ADS  -- 
the  static  calling  structure  or  tree  diagram  of  the  program  under  devel- 
opment . 


Figure  2.  Expansion  and  update  of  ADS  documentation. 


Figure  3.  Production  of  reports  directly  from  documentation  files 
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PROGRAM  MAINdNPUT. OUTPUT) 

T I TLF  ! = 

main  - MAIN  program  OF  MANUAL  FXAMPLE 
autmor:=  this  systfm  programmer 
purpose := 

THF  PURPOSF  of  THIS  program  is  TO  ILLUSTRATf  how  A program  IINOFP 
OEVF.LOPMFNT  MIGHT  UTII  I7E  AOS.  THF  PROGRAM  IS  OUTLINFS  BY  THE 
MAIN  program.  THFN  as  OTHER  ROUTINES  APE  DFVELOPFO  THEY  WILL  RF 
AOOFO  to  THE  DOCUMENTATION  files. 

call  SUR1 

CALL  SURP 

CAt  L SUB”) 


STOP 

ENO 


Figure  4.  FORTRAN  source  code  for  a main  program. 
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Figure  5.  Compiler  reference  map  for  program  in  Figure 


?5  JUL  78  11.55.54  CERL  - AOS  - MESSAGE  OUTPUT  PAGF 


TITLE  THE  AOS  USER  MANUAL  EXAMPLE  t 
PRINT  NARROW  (DUMP)  FOR  MAINI 
ENDJ 

Figure  6.  Sample  ADS  commands. 


?5  JUL  70  11.55.54  CERL  - AOS  - VEdsION  1.0  PAGE 

THE  AOS  USER  MANUAL  EXAMPLE 

OUMP  AS  OF  ?5  JUL  78-MAIN 


TITLE. 

main  - MAIN  PROGRAM  OF  MANUAL  EXAMPLE 
AUTHOR. 

THIS  SYSTEM  PROGRAMMER 
PURPOSF. 

THE  PURPOSE  OF  THIS  PROGRAM  IS  TO  ILLUSTRATE  HOW  A PROGRAM  UNOER 
DEVELOPMENT  MIGHT  UTILI7E  ADS.  THE  PROGRAM  IS  OUTLINES  BY  The 
MAIN  PROGRAM . THEN  AS  OTHER  ROUTINES  ARE  DEVELOPED  THEY  WILL  BE 
AODEO  TO  THE  DOCUMENTATION  FILES. 

FILES  USED  IN  MAIN  APF  — 

INPUT  OUTPUT 

VARIABLE  DICTIONARY  FOR  ROUTINE  MAIN  — **  NONE  ** 

THIS  A MAIN  PROGRAM  OF  LENGTH  7 WORDS. 

ROUTINES  CALLED  BY  MAIN  ARE  — 

SUB  1 SUR2  SUB3 

COMMON  BLOCKS  CALLED  BY  MAIN  ARE  — **  NONE  «* 


1 


1 


THE  ROUTINES  WHICH  CALL  MAIN  ARE  — **  NONF  ** 

I 

Figure  7.  Sample  ADS  report. 
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subroutine  suri 
T I tlE  : = 

SUR 1 - THE  FIRST  SUBROUTINE  OF  THE  PROGRAM  TO  HE  IMPLEMENTED 
AUTHOR : = THIS  SYSTEM  PROGRAMMER (SI . 

PURPOSE : = 

THE  PURPOSE  OF  THIS  ROUTINES  IS  TO  SHOW  HOW  ONE  MIGHT  AOO  A 
ROUTINE  TO  A DOCUMENTATION  FILE  UNDER  DEVELOPMENT. 

CALL  SUBRTE 
RE  TURN 
END 

Figure  8.  Sample  of  source  code  for  a subroutine. 


SUBROUTINE  SUB  1 


7600  7600  OPT  * 1 


SURPOUTINE  SHR 1 
T I TI  E : = 

SURl  - THE  FIRST  SUBROUTINE  OF  THE  PROGRAM  TO  BE  IMPLEMENTED. 
AUTHOR : = THIS  SYSTEM  PROGRAMMER ( S ) . 

PURPOSE := 

THE  PURPOSE  OF  THIS  ROUTINES  IS  TO  SHOW  HOW  ONE  MIGHT  ADD  A 
ROUTINE  TO  A DOCUMENTATION  FILE  UNDER  DEVELOPMENT. 

CALL  SUBRTE 

RETURN 

END 


SYMBOLIC  REFERENCE  MAP  <P=3> 


ENTRY  POINTS 
1 SUB  2 

EXTERNALS 

SUBRTF 

STATISTICS 

PROGRAM  LENGTH 


OFF  LINE  fl 

1 

TYPE  ARGS 
0 


REFERENCES 

10 


REFERENCES 

9 


Figure  9.  Sample  of  reference  map  for  a subroutine. 


PPINT  NARROW  (DUMP)  FOR  UPDATED  ROUTINE* 

fnd; 


Figure  10.  Sample  ADS  commands  to  update  documentation  by  adding  subroutine. 


CERL  - AOS  - MESSAGE  OUTPUT 


print  NARROW  (Dump)  FOR  ALL  ROUTINES* 

*•  WARNING  RFQllFSTED  READ  OE  RECORO  (ROUTINE)  - 

•o  WARNING  RFOUESTEO  READ  OF  RECORO  (ROUTINE)  - 

• • WARNING  RFOUESTEO  READ  OF  RECORO  (ROUTINE)  - 

OPAW  NARROW  FULL  TREE* 

FNP« 


_ $UR2  » RFCORP  NOT  ON  MASTER  FILF 
_ SUB3  • RECORD  NOT  ON  MASTER  FILF 
- SUBRTE  . RECORO  NOT  ON  MASTER  FILF 


Figure  11.  Sample  ADS  commands  used  only  for  production  of  external 
documentation  reports. 


CERL  " ADS  - VERSION  1.0 
THE  ADS  USER  MANUAL  EXAMPLE 


TREE 


MAIN. 


!_SUB1 

I !*SUBRTF 

! *SUB? 

1 *SUB3 

Figure  12.  Tree  diagram  of  program  under  development. 
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3 ADS  SOURCE  CODE  INPUT  — FORMAT 


There  are  19  documentation  categories  in  which  a programmer  may 
store  information  regarding  a program  under  development.  These  catego- 
ries are  listed  in  Table  1;  detailed  explanations  of  each  category  are 
found  in  Appendix  A. 

Special  ADS  comment  cards  ("CD"  in  columns  1 and  2 of  the  source 
code)  are  used  to  insert  documentation  regarding  a program  under  devel- 
opment to  ADS.  To  enter  an  ADS  documentation  comment  (1)  type  "CD"  in 
columns  1 and  2 of  the  source  code,  (2)  type  the  title  of  the  documen- 
tation category  selected  from  the  19  provided  by  ADS,  (3)  type  (4) 

type  "CD"  in  columns  1 and  2 of  the  source  code,  followed  by  the  first 
line  of  the  comment,  and  (5)  repeat  step  4 until  the  comment  is  com- 
pl ete. 

For  example,  the  format  for  an  ADS  comment  on  the  purpose  of  a pro- 
gram is 

CD  PURPOSE : = 

CD  THE  PURPOSE  OF  THIS  PROGRAM  IS  TO  GENERATE  MOVE  DIRECTIVES  TO 
CD  SORT  OLDPL  --  UPDATE  LIBRARY.  UP  TO  THREE  LEVELS  OF  DECKS 
CD  CAN  BE  EXCLUDED  FROM  THE  TOTAL  SORT  (AND  THEN  ARE  SORTED  AMONGST 
CD  THEMSELVES).  COMDECKS  ARE  SORTED  SEPARATELY  FROM  MAIN  DECKS.  EACH 
CD  t EVFL  MUST  ALSO  INPUT  A DECK  NAME  THAT  ALL  DECKS  IN  THE  LEVEL  WILL 
CD  FOLLOW  --  THE  DIRECTIVE  WILL  BE  OF  FORM: 

The  above  will  appear  in  the  external  documentation  report  as: 

PURPOSE. 

THE  PURPOSE  OF  THIS  PROGRAM  IS  TO  GENERATE  MOVE  DIRECTIVES  TO 
SORT  OLDPL  --  UPDATE  LIBRARY.  UP  TO  THREE  LEVELS  OF  DECKS  CAN 

BE  EXCLUDED  FROM  THE  TOTAL  SORT  (AND  THEN  ARE  SORTED  AMONGST 

THEMSELVES).  COMDECKS  ARE  SORTED  SEPARATELY  FROM  MAIN  DECKS. 

EACH  LEVEL  MUST  ALSO  INPUT  A DECK  NAME  THAT  ALL  DECKS  IN  THE 
LEVEL  WILL  FOLLOW  --  THE  DIRECTIVE  WILL  BE  OF  FORM: 

The  user  can  control  the  paragraphing  of  the  comment  text  by  in- 
serting one  or  all  of  the  following  flags  in  the  source  code: 

CD$_  Begin  new  line  at  left  margin 

CDS  Begin  new  line;  retain  tab  setting  indicated  in  preceding  line 

CD  No  new  line;  line  may  be  run  on  with  preceding  line 

CDS Begin  new  line;  reset  tab  to  indent  5 spaces 
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Table  1 


ADS  Documentation  Categories 


TITLE 

AUTHOR 

DATE  WRITTEN 
REFERENCES 
LOCATION 
METHOD 

CONTROL  CARDS 
REMARKS 
SYSTEM 
PURPOSE 


FLOW 

FILES 

ALGORITHM 

SYSTEM  DEPENDENCIES 
NON  SYSTEM  DEPENDENCIES 
MACHINE  DEPENDENCIES 
IMPLEMENTATION  DEPENDENCIES 
VARIABLE  DICTIONARY 
REVISED  (date) 


CDS  Begin  new  line;  reset  tab  to  indent  10  spaces. 

00$  Begin  new  line;  reset  tab  to  indent  15  spaces. 

For  an  example  of  a program  source  code  implanted  with  AOS  comments 
(documentation  category,  initial  comments,  and  subsequent  paragraphing 
flags)  and  the  resultant  output  (external  documentation  reports),  see 
Figures  13  and  14. 


Common  Block  Input 


ADS  comments  regarding  common  blocks  within  a program  are  strictly 
limited  to  two  ADS  documentation  categories;  TITLE  and  VARIABLE  DICTIO- 
NARY. In  addition,  ADS  comments  for  common  blocks  must  appear 
contiguously  in  the  source  code.  For  example: 

C0MM0N/C0M1/VAR1 ,VAR2 
CD  TITLE := 

CD  C0M1  - TITLE  FOR  C0M1 
CD  VARIABLE  DICTIONARY : = 

CD  VAR1  - DEFINITION  OF  VAR1 
CD  VAR2  - DEFINITION  OF  VAR 2 

Any  attempt  to  enter  ADS  comments  other  than  TITLE  or  VARIABLE  DIC- 
TIONARY, or  to  type  comments  noncontiguously , will  probably  result  in 
the  loss  of  that  common  block  documentation. 


Variable  Dictionary  Input 

Variable  dictionary  comments  (under  the  heading  "VARIABLE  DICTIO- 
NARY^") must  be  definitions  for  variable  names  al ready  in  the  source 
code.  To  enter  a variable  dictionary  comment,  (l)  type  "CD"  in  columns 
1 and  2 of  the  source  code  followed  by  "VARIABLE  DICTIONARY:=" , (2)  type 
"CD"  in  columns  1 and  2 of  the  source  code,  followed  by  the  variable 
name  to  be  defined  and  and  (3)  type  the  definition. 

For  example,  a variable  dictionary  comment  implanted  in  the  source 
code  as 

CD  VARIABLE  DICTIONARY : = 

CD  FLAGV  - FLAG  VARIABLE 

CDS  l-->  INPUT  IS  FROM  DISK  FILE 

CDS  2 — > INPUT  IS  FROM  CARDS 

will  appear  in  the  external  report  as 


CO  T!Tir 

CD  ROI T - RT AD  A SET  OF  DICKS  TO  IXCLIIDE  f ROM  GENERAL  SORTING 
CD  PURPOSE:* 

CD  I HE  PURPOSE  OF  THIS  PROGRAM  IS  10  GtNIHAH  MOVE  D1RECIIVFS  TO 
CD  SPP.r  AN  OLDPL  --  IIPDAIE  URRARY.  IIP  TO  TIIRI  E II  VIES  OF 

CD  DECKS  CAN  RE  EXCLUDED  I ROM  THE  TOTAL  SORT  (AND  ARE  TIILN 

CD  SORTED  AMONGST  THEMSELVES) . COMDFCKS  ARE  SORTED  SEPARATELY 
CD  FROM  MAIN  DECKS.  EACH  LEVEL  MUST  ALSO  INPUT  A DECK  NAMC 

CD  THAT  ALL  DECKS  IN  THE  LEVEL  WILL  FOLLOW  — THE  DIRECTIVE 

CD  WILL  BE  OF  FORM: 

CDS "*M()VE  <DECK  NAMES , < INPUT  DECK  NAMES" 

CDS TO  LEVEL  DECKS  ONE  PUTS  IN  CARDS  OF  FORM: 

CD$_  COL  1—9.  NAME  OF  EXCLUDED  DECK 
C0$_  COL.  10  BLANK.  1 , OR  2 

CDS  DECK  NAMES  ARE  SORTED  AND  MOVE  DIRECTIVES  GENERATED 

CD  SUCH  THAT  THE  FINAL  ORDER  OF  THE  UPDATE  OLDPL  WILL 

CD  BE: 

CC$_  COMDECKS, 

COS  DECKS  (INPUT  CARD  NAMES)  WITH  COL  10  = 2, 

CDS  DECKS  (INPUT  CARD  NAMES)  WITH  COL  10  * 1, 

CCS  OECKS  (NOT  COMDECKS)  NOT  SPECIFIED  ON  INPUT  CAROS. 

CCS  NOTE  — DECKS  (INPUT  CARD  NAMES)  WITH  COL  10  = BLANK 

CO  ARE  NOT  SORTED!  THESE  DECKS  CAN  REMAIN  IN  PRESENT  PLACES 

CD  IN  THE  OLDPL  AND  BE  USED  FOR  POSITIONING  OTHER  DECKS. 

COS  THE  PROGRAM  USES  THE  BASIC  OUTPUT  (L-A14)  FROM  THE  UPDATE 
CD  PROGRAM  AS  INPUT  (TAPEI). 


Figure  13.  FORTRAN  source  code  implanted  with  ADS  comments. 


TITLE. 

RDIT  - READ  A SET  OF  DECKS  TO  EXCLUDE  FROM  GENERAL  SORTING 
PURPOSE. 

THE  PURPOSE  OF  THIS  PROGRAM  IS  TO  GENERATE  MOVE 
DIRECTIVES  TO  SORT  OLDPL  — UPDATE  LIBRARY.  UP  TO 
THREE  LEVELS  OF  DECKS  CAN  BE  EXCLUDED  FROM  THE 
TOTAL  SORT  (AND  ARE  THEN  SORTED  AMONGST  THEMSELVES). 
COMDECKS  ARE  SORTED  SEPARATELY  FROM  MAIN  DECKS. 

EACH  LEVEL  MUST  ALSO  INPUT  A DECK  NAME  THAT  ALL 
DECKS  IN  THE  LEVEL  WILL  FOLLOW  — THE  DIRECTIVE 
WILL  BE  OF  FORM: 

"‘MOVE  <DECK  NAMES , <!NPUT  DECK  NAMES" 

TO  LEVEL  DECKS  ONE  PUTS  IN  CARDS  OF  FORM: 

COL  1 — 9 . NAME  OF  EXCLUDED  DECK 
COL.  10  BLANK  1 OR  2 
DECK  NAMES  ARE  SORTED  AND  MOVE  DIRECTIVES 
GENERATED  SUCH  THAT  THE  FINAL  ORDER  OF  THE 
UPDATE  OLDPL  WILL  BE: 

COMDECKS, 

DECKS  (INPUT  CARO  NAMES)  WITH  COL  10  * 2, 

DECKS  (INPUT  CARD  NAMES)  WITH  COL  10  ■ 1, 

DECKS  (NOT  COMDECKS)  NOT  SPECIFIED  ON  INPUT  CARDS. 

NOTE  — DECKS  (INPUT  CARD  NAMES)  WITH 
COL  10  = BLANK  ARL  NOT  SORTED!  THESE 
DECKS  CAN  REMAIN  IN  PRESENT  PLACES 
IN  THE  OLDPL  AND  BE  USED  FOR 
POSITIONING  OTHER  DECKS. 

THE  PROGRAM  USES  THE  BASIC  OUTPUT  (L  - A14) 

FROM  THE  UPDATE  PROGRAM  AS  INPUT  (TAPEI). 


Figure  14.  ADS  Output  from  Figure  13. 


VARIABLE  DICTIONARY. 

FLAGV  - FLAG  VARIABLE 

1 — > INPUT  IS  FROM  DISK  FILE 

2 -->  INPUT  IS  FROM  CARDS 

(Note  that  variable  dictionary  comments  containing  the  variable 
name  are  indented  ten  spaces.  The  typed  by  the  user  following  the 
variable  name  has  the  effect  of  indenting  the  tab  setting  10  spaces  to 
the  right  of  the  left  margin  --  however  this  indenting  is  not  under  user 
control ) . 


4 ADS  PROGRAM  CONTROL  AND  OPTIONS 


This  chapter  further  defines  the  syntax  of  ADS  commands  and  pro- 
vides examples  of  various  report  retrieval  options-  Words  in  capital 
letters  must  appear  as  written.  Words  inclosed  in  angle  brackets  (<  >) 
must  be  supplied  by  the  user  from  an  optional  list.  Symbols  not 
inclosed  in  brackets  etc.)  must  be  included  as  written. 

COMMON(S)  indicates  that  either  COMMON  or  COMMONS  may  be  used. 


External  Reports:  Filing  and  Retrieval 

The  contents  of  documentation  reports  generated  by  ADS  may  be  de- 
fined by  the  user.  These  report  names  (and  definitions)  are  stored  on 
the  documentation  files  and  may  be  retrieved,  b_  name,  when  producing  a 
report  (via  the  PRINT  command). 

APS  provides  two  predefined  report  names  on  euch  documentation 
file:  ABSTRACT  and  DUMP.  ABSTRACT  provides  the  ADS  documentation  cate- 
gories: TITLE,  AUTHOR,  PURPOSE,  METHOD,  ALGORITHM,  and  REFERENCES. 

DUMP,  on  the  other  hand,  is  a comprehensive  listing  of  al 1 possible  ADS 
documentation  stored  for  a program  or  common  block. 

To  define  a report,  the  user  types: 

REPORT  <name>  = <section  1 i s t > ; 

<Name>  is  user  supplied  and  must  be  less  than  or  equal  to  10  typed  char- 
acters. <Section  1 i s t > is  the  documentation  categories  listed  in  the 
order  in  which  they  are  to  be  printed  in  the  external  report;  each  docu- 
mentation category  is  separated  from  the  one  preceding  it  by  a comma. 

The  final  documentation  category  typed  by  the  user  is  followed  by 
For  example: 

REPORT  ABSTRACT  = TITLE , AUTHOR .PURPOSE , METHOD , ALGOR ITHM, REFERENCES ; 
(NOTE:  The  above  are  the  elements  included  in  the  ADS  ABSTRACT  report.) 

External  documentation  reports  produced  by  ADS  can  be  used  by  pro- 
grammers as  final  documentation,  progress  reports,  or  as  information  for 
other  programmers.  Also,  by  attaching  the  proper  documentation  files, 
individuals  other  than  the  original  programmer  are  able  to  produce  re- 
ports on  the  program(s)  under  development. 

Report  names  are  included  in  the  documentation  files  and  may  be  de- 
fined for  each  program's  documentation  files  and  retrieved,  by  name, 
when  producing  a report. 
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Additional  APS  Documentation  Output 

In  addition  to  the  19  documentation  categories  already  described 
(see  Table  1),  four  other  type';  of  AOS  output  can  be  requested  by  the 
user  for  inclusion  in  an  external  documentation  report.  They  are: 

ENTRY  POINTS,  ROUTINES  CALLED,  COMMON  BLOCKS  CALLED,  and  CALLED  BY. 

ENTRY  POINTS  gives  general  information  about  the  program:  the 
entry  point  names  (if  more  than  one);  the  date  documentation  was  entered 
onto  the  documentation  files;  the  type  of  routine  (PROGRAM,  SUBROUTINE, 
FUNCTION);  and  the  routine's  length.  ROUTINES  CALLED  specifies  the  rou- 
tines called  by  the  program  plus  the  inline  functions  used  by  the  pro- 
gram. COMMON  BLOCKS  CALLED  lists  the  common  blocks  called  by  the  pro- 
gram. A maximum  of  100  possible  items  is  assumed  for  both  ROUTINES 
CALLED  and  COMMON  BLOCKS  CALLED.  CALLED  BY  gives  the  names  of  the  rou- 
tines and  common  blocks  calling  the  program  under  development.  In  addi- 
tion, CALLED  BY  lists  which  submodules  use  the  files  of  the  main  pro- 
gram. 


Delete  Opt  ion 

Another  option  of  the  ADS  program  input  is  the  ability  to  delete 
information  from  the  documentation  files  about  a particular  routine, 
common  block,  or  report  name.  The  format  for  this  command  is: 

DELETE  <record  type>  (<name  list>); 

<Record  type>  requires  the  user  to  type  one  of  the  following:  ALL,  ROU- 
TINE, COMMON,  or  REPORT.  <Name  Iist>  specifies  the  routines  common 
blocks,  etc.,  to  be  deleted  of  type  Krecord  type>.  ALL  will  delete  all 
types  of  the  names  in  <name  list>.  For  example,  "DELETE  ROUTINE  (MAIN, 
SUB  1 ) ; " deletes  all  references  to  routines  named  MAIN  arid  SUB1.  "DELETE 
REPORT  (ABSTRACT);”  deletes  all  references  to  report  ABSTRACT.  "DELETE 
ALL  (MAIN,  C0M1 ) ; " searches  routines,  commonbl ocks , and  report  lists  and 
deletes  all  references  to  MAfN  and  C0M1  entries. 


Print  Option 


To  print  reports  from  the  documentation  file,  the  user  types: 

PRINT  Creport  widthN  <paging>  (Creport  Iist>)  FOR  Krecord  1 i s t > ; 

For  Creport  width>  Ahe  user  types  either  NARROW  or  WIDE.  NARROW  reports 
are  suitable  for  8 x 10-1/2-in.  reproduction.  WIDE  reports  use  the  full 
width  of  the  printer  paper  (14  x 11  in.).  <Paging>  is  one  of  PAGED  or 
UNPAGED.  PAGED  reports  (default)  start  each  new  item  in  Crecord  list> 
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on  a single  page.  Reports  are  also  paged  within  records  so  a report 
will  be  spaced  properly  over  page  boundaries.  <Report  1 i s t > requires 
the  user  to  type  the  list  report  names,  separated  by  commas,  to  be 
printed  for  each  occurrence  of  a record  in  <record  list>.  When  typing 
<record  list>  the  user  may  choose  one  of  the  following:  (<name  list)), 
ALL  ROUTINE  (S),  ALL  COMMON(S),  UPDATED  ROUTINE  (5?) , or  UPDATED  COMMON ( S ) - 
The  <name  list>  specifies  a set  of  routines,  common  blocks,  etc.  (sepa- 
rated by  commas)  for  which  a specified  external  report  will  be  produced. 
The  ALL  prefix  prints  reports  for  all  routines  or  common  blocks 
presently  on  the  documentation  files.  Additionally,  warning  errors  are 
printed  for  each  report  not  yet  on  documentation  files.  The  UPDATED 
prefix  will  print  reports  for  each  routine  or  common  block  included  on 
the  documentation  files  for  this  tun.  Thus,  ADS  can  update  the  documen- 
tation files  and  produce  reports  in  a single  run.  For  each  occurrence 
of  a "report  name"  in  <record  1 i st > , a report  detailing  that  "report 
name"  will  be  produced,  showing  the  ADS  documentation  categories  in  the 
order  indicated  by  the  "report  name".  For  example,  "PRINT  NARROW  (DUMP) 
FOR  ALL  ROUTINES;"  produces  a DUMP  report  for  all  routines  defined  on 
the  documentation  files.  "PRINT  NARROW  (DUMP)  FOR  (ABSTRACT,  DUMP);" 
produces  a REPORT  DEFINE  report  for  the  two  reports  ABSTRACT  and  DUMP. 
This  command  will  also  produce  a DUMP  report  for  any  routines  or  common 
blocks  with  names  ABSTRACT  or  DUMP. 


Tree  Option 

The  "tree"  option  produces  a diagram  of  the  routines  on  the  docu- 
mentation files  of  the  program  under  devetopment  by  using  the  cross-ref- 
erencing information  available  for  each  routine.  The  format  is  fixed  by 
ADS  and  therefore  cannot  be  modified  by  the  user.  The  format  for  re- 
questing the  tree  option  from  ADS  is: 

DRAW  Ctree  type>  Creport  width>  TREE  <routine>  Cdepth); 

For  <tree  type),  the  user  types  either  FULL  or  COMPRESSED.  For  Creport 
width),  the  user  types  either  NARROW  or  WIDE.  CRoutine)  is  optional;  if 
Croutine)  is  included,  ADS  will  use  Croutine)  as  the  root  of  the  tree. 

If  Croutine)  is  not  included,  ADS  will  use  the  main  program  as  the  root. 
If  more  than  one  main  program  resides  on  the  documentation  files,  a tree 
will  be  drawn  for  each  main  program.  CDepth)  specifies  the  number  of 
levels  to  be  included  in  the  tree.  (If  Cdepth)  is  omitted,  full  depth 
is  assumed.)  A FULL  tree  includes  all  routines  indicated  by  the  cross- 
referencing;  a COMPRESSED  tree  does  not  include  each  routine  of  a pre- 
viously drawn  branch.  For  example,  "DRAW  FULL  WIDE  TREE  ADSDOC  ;" 
should  draw  a tree  the  entire  ADS  program.  However,  "DRAW  COMPRESSED 
NARROW  TREE  ADSRPT  3 ;"  will  draw  only  the  subtree  at  routine  ADSRPT 
for  three  levels  of  subroutine  calls. 
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The  tree  option  displays  the  basic  calling  sequence  of  the  program. 
A FULL  tree  shows  each  routine  called  at  each  level.  For  example,  "DRAW 
FULL  NARROW  TREE  MAIN;"  might  produce: 

MAIN 

I SUB3 

I | SUB1 

I TIMER 

j | *SEC0ND 

I SUB? 

i [TIMER 

| *SEC0ND 

, SUB1 

, TIMER 

I *SEC0ND 


whereas  "DRAW  COMPRESSED  NARROW  TREE  MAIN;"  would  produce 


MAIM 


SUB3 


SUB1 


TIMER 


'sub? 

[TIMER* 

1 SUB 1 * 


|*SEC0ND 


An  "*"  before  a name  indicates  the  routine  is  not  on  the  master 
documentation  files.  An  "*"  following  a name  indicates  that  the  branch 
has  already  been  displayed. 


Other  Opt  ions 

The  user  also  has  the  option  of  assigning  a title  to  the  documen- 
tation files.  This  title  will  be  printed  on  the  heading  of  each  report 
and  stored  in  the  documentation  files.  (Additional  headings  on  each 
report  page  will  contain  a page  number,  the  date  and  time  of  the  run, 
the  report  name,  record  identifer,  and  date  of  the  record  on  the  docu- 
mentation files.)  To  assign  a system  title,  the  user  types: 

TITLE  characters; 


Up  to  80  typed  characters  are  allowed  for  the  title.  Once  the  title  is 
stored  on  the  documentation  files  it  need  not  be  input  again.  For  exam- 
pi  e : 


TITLE  THE  AUTOMATED  DOCUMENTATION  SYSTEM  (ADS); 

The  ADS  program  will  accept  and  process  each  statement  input,  to  it. 
Processing  of  the  input  begins  when  ADS  finds  the  symbol  indicating  the 
end  of  the  statement,  i.e.,  If  an  error  occurs  during  the  parsing 
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**;  * 


of  the  statement,  ADS  skips  until  it  locates  the  semicolon,  effectively 
ignoring  the  statement.  ADS  first  processes  any  reference  maps  and 
source  code  the  user  has  attached  before  beginning  production  of  an  ex- 
ternal report. 

To  terminate  the  ADS  program  the  user  types: 

END; 

ADS  can  be  run  either  as  a batch  or  interactive  program.  ADS  re- 
ports and  various  informative  messages  are  written  to  separate  local 
files.  The  reports  are  formatted  for  printers;  however  ADS  informative 
messages  can  be  received  either  on  printer  or  interactive  terminal 
output . 

For  interactive  usage  (though,  of  course,  batch  runs  will  accept 
these  statements),  three  additional  statements  are  allowed: 

HELP; 

ECHO;  (default) 

NOECHO; 

ECHO  and  NOECHO  turn  on  and  off  echoing  user  input  to  the  ADS  program. 
HELP  provides  some  information  about  the  form  of  the  input  statements. 

During  the  execution  of  ADS,  error  messages  may  be  printed.  These 
error  messages  inform  the  user  of  invalidities  in  the  input,  in  source 
code  processing,  and  in  documentation  files  processing.  For  example,  if 
the  user  inputs  "PRONT  NARROW  (DUMP)  FOR  MAIN;"  ADS  will  respond:  "**** 
SEVERE  UNKNOWN  COMMAND"  and  continue  to  the  next  input  command.  If,  in 
the  source  code,  a routine  does  not  have  an  "end"  card,  "SEVERE  MISSING 
END  CARD,  RESTART  WITH  FOLLOWING  CARD"  will  appear.  In  the  next  output 
line,  the  card  restarting  source  code  parsing  will  be  printed.  If  a 
routine  is  referenced  (i.e,  called  by  a routine  that  has  been  documen- 
ted), but  is  not  found  on  the  documentation  files,  ADS  will  print:  "** 
WARMING  REQUESTED  READ  OF  RECORD  (ROUTINE)  — EOF."  The  message  iden- 
tifies what  kind  of  record  (in  this  case  a ROUTINE  named  EOF)  cannot  be 
found  in  any  ROUTINE  COMMON  or  REPORT  category  of  the  documentation 
file.  This  message  will  only  appear  once  per  execution  through  the  read 
of  the  record  may  be  requested  many  times. 
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A complete  ADS  processing  run  may  then  look  like 


1 


5 ADS  JOB  CONTROL 


As  indicated  in  Chapter  2,  ADS  is  designed  for,  and  currently  exe- 
cutable with,  the  Control  Data  Corporation  (CDC)  FTN  version  4.6  com- 
piler. An  attempt  has  been  made  to  make  the  program  portable  to  comput- 
ers of  other  manufacturers;  however,  reasonably  extensive  changes  in 
word  size,  formats,  characters,  file  handling,  etc.,  are  necessary 
before  this  can  be  accomplished. 

Assuming  that  the  ADS  program  is  ready  to  be  executed  at  the  CDC 
computer  facility  chosen  by  the  user,  certain  control  card  sequences  are 
necessary  to  execute  the  program  and  attach  and  save  the  required  files. 

The  internal  names  used  by  the  ADS  program  are: 

INPUT-  The  ADS  commands  described  in  Chapter  4. 

OUTPUT-  The  printed  output  file  containing  informative  diagnostics 
and  optional  echo  of  user-supported  ADS  commands. 

RPTOUT-  The  reports  created  by  this  run  of  ADS. 

RLFFL-  The  reference  map  information  created  by  the  FORTRAN 

compiler.  Only  routines  on  this  file  are  updated 
this  run. 


SRCFL- 


MASBK- 


INVBK- 


The  FORTRAN  source  code  containing  the  special  ADS 
comment  cards.  The  routine  found  in  the  SRCFL  must 
match  that  of  the  REFFL. 

The  master  random  access  file  containing  the  documentation 
records  and  report  definitions  for  the  system. 

This  file  should  be  attached  when  updates  to 
documentation  or  reporting  of  documentation  are 
done.  The  file  MASFL  contains  old  documentation 
plus  any  updates  performed  and  should  be  saved  whenever 
changes  to  the  documentation  are  to  be  kept. 

The  master  random  access  file  containing  the  cross- 
referencing  records  (see  CALLED  BY,  p?6  ) for 
routines  and  common  blocks.  This  file  should  oe 
attached  whenever  updates  to  documentation  or 
reporting  of  documentation  are  required. 

The  file  INVFL  contains  old  invert  records 
plus  any  updates  performed  and  should  be  saved 
whenever  changes  to  the  documentation  are  to  be  kept. 
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MASBK  and  INVBK  are  the  local  file  names  for  the  "old"  documen- 
tation files  used  as  input  to  ADS.  MASFL  and  INVFL  are  the  new,  updated 
documentation  files  created  by  ADS.  For  a REFFL  input  example,  see  Ap- 
pendix D.  For  an  example  of  a complete  ADS  run,  see  Appendix  E. 

Although  this  report  outlines  general  ADS  user  instructions,  it 
should  be  noted  that  the  exact  control  cards  used  for  attaching  and 
saving  programs  and  files  differ  with  various  computer  sites  depending 
upon  the  site  operating  system. 

For  a typical  example  using  the  input  outlined  above,  see  Figure 
15.  In  addition,  documentation  files  may  be  too  big  to  store  inexpen- 
sively on  disks  and  probably  should  be  kept  on  tape. 


<Job  cards,  accounting  cards) 

Get/create  SRCFL  the  source  code  to  be  run  through  ADS  (Optional). 
FTN, I=SRCFL,  L=REFFL,Q,  R=<>. 


Invoke  FTN  for  installation  using  SRCFL, 
creating  REFFL  for  this  run. 

R=  <>,  the  user  may  chose 
the  reference  map--l  or  2 or  3. 

Get  ADSDOC  Get  executable  code  of  ADS. 

Get  MASBK  Get  master  documentation  file,  if  one 
exists. 

Get  INVBK  Get  master  invert  documentation  file,  if 

one  exists. 

ADSDOC.  Execute  ADS. 

REWIND, RPTOUT. 

COPY, RPTOUT, OUTPUT. 

Save  MASFL  / Save  Master  and  invert  documentation 
files,  if  desired. 

Save  INVFL 

7/8/9  (End  of  Record  Card) 

ADS  Input  Directives 

6/7/8/9  (End  of  Information  Card) 

Figure  15.  ADS  command  example. 
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APPENDIX  A: 


ADS  DOCUMENTATION  CATEGORY  AND  USAGE  GUIDE 


This  appendix  is  in  semi  tabular  format.  Each  possible  documen- 
tation category  (section  title)  is  shown  in  capital  letters  followed  by 
a brief  description  of  information  that  might  be  included  in  a typical 
documented  code.  The  least  allowable  format  for  each  documentation  cat- 
egory is  in  capital  letters  inclosed  by  parentheses. 

ALGORITHM  (ALG):  denotes  a particular  type  of  algorithm  being  used 
in  a routine.  This  category  is  similar  to  METHOD  but  might  be  particu- 
larly applicable  when  the  method  is  not  well  known  or  is  an  adaptation 
of  another  method  to  a new  purpose.  Also  the  specification  of  a partic- 
ular algorithm  may  make  the  documentation  action  clearer  for  some  appli- 
cations (e.g.  numerical  rather  than  information  systems). 

Exampl es : 

1.  This  routine  uses  the  Collins  Algorithm  for  polynomial  division 
as  outlined  by  Knuth,  Vol  2. 

2.  This  routine  adapts  the  Taylor  series  for  the  sine  of  an  angle 
to  the  constraints  outlined  in  the  functional  requirements  of  the 
system. 

AUTHOR  (AUT):  shows  the  author  of  the  routine.  While  the  AUTHOR 
section  may  not  be  useful  in  final  documentation,  it  can  be  very  useful 
to  the  manager  and  to  other  programmers  in  the  software's  developmental 
stages. 

CONTROL  CARDS  (CON):  aids  the  programmer  using  the  system/routine. 
In  general , systems  usually  need  more  instructions  than  a documentation 
category  can  provide  though,  for  some  systems,  this  category  could  indi- 
cate catalogued  procedure  usage.  The  parameters  to  the  catalogued  pro- 
cedure could  be  described  in  more  detail  in  a user's  manual.  This  cate- 
gory could  also  serve  as  instruction  to  a user  of  a simple  program  or 
routine,  and  could  include  a user  library  that  contains  the  program/ rou- 
tine. Since  explicit  control  cards  also  change  from  operating  system  to 
operating  system,  this  category  could  become  more  confusing  than  useful 
if  an  attempt  is  made  to  document  all  systems.  Additionally,  "JCL"  can 
be  used. 

DATE  WRITTEN  (DAT):  indicates  when  the  routine  was  written.  This 
category  may  be  useful  to  indicate  what  routines  may  have  been  written 
prior  to  some  operating  system  change.  In  developing  systems,  the  date 
written  can  aid  in  displaying  the  current  stage  of  the  development. 
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FILES  (FIL):  indicates  the  files  used  by  the  program/ system.  This 
category  should  appear  only  in  a main  program  becausp  the  file  documen- 
tation record  exists  as  a header  record  on  the  documentation  files.  A 
maximum  of  64  files  is  allowed  for  the  entire  system.  In  addition  to 
the  names  of  the  files,  this  category  can  indicate  usage  of  the  file, 
type  of  access,  etc. 

Examples: 

1.  Card  input  is  typically  a formatted  file. 

2.  Certain  files  can  be  accessed  randomly,  sequentially,  or  word 
addressable. 

3.  Special  formatted  files  (such  as  weather  taoes  from  National 
Atmospheric  and  Oceanic  Administration  [NOAA]),  may  take  special  consid- 
eration. For  example,  the  FILE  control  card  necessary  to  process  the 
file  could  he  included. 

FLOW  (FLO):  illustrates  the  logical  flow  of  the  code.  This  cate- 
gory should  be  used  at  the  top  level  of  system  or  for  a complex  sub- 
module.  Indentation  level  options  allowed  by  ADS  can  be  particularly 
effective  in  this  section.  Indenting  can  aid  in  displaying  "while" 
loops,  etc. 

For  example: 

LOGICAL  FLOW. 

CALL  INITIALIZATION  ROUTINES  (ADINIT,  FHINIT,  PINIT) 

WHILE  NOT  EOF  (REFFL)  DO 

READ  REFERENCE  MAP  FOR  A ROUTINE. 

SCAN  THE  SOURCE  CODE  PARSING  DOCUMENTATION  FOR  ROUTINE. 

PERFORM  USER  INPUT  COMMANDS. 

PERFORM  ENP-OF-JOB  PROCESSING. 

IMPLEMENTATION  DEPENDENCIES  (IMP  PEP):  defines  the  dependencies  of 
a system/ rout i ne  implementation.  These  dependencies  could  be  of  several 
types  --  certain  operating  system  characteristics  used  by  the 
system/routine;  assumptions  made  by  the  routine  about  its  parameters; 
new  features  in  the  system  necessary  to  implement  this  code.  In  each 
case,  the  documented  code  may  work  only  as  long  as  the  implied  assump- 
tions are  in  effect.  It  may  not  be  good  programming  practice  to  rely  on 
certain  "defects"  in  the  system  being  used,  but  it  is  occasionally  nec- 
essary. If  certain  assumptions  are  implicit  in  implementing  code,  then 
these  assumptions  should  be  documented. 
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LOCATION  (LOC):  details  the  location  of  the  source/object  code. 

MACHINE  DEPENDENCIES  (MAC  DEP):  defines  the  dependencies  of  the 
system/ routi ne  on  a particular  machine's  architecture.  For  example, 
using  a certain  word  size  or  arithmetic  precision  can  make  a system 
dependent  on  the  machine  of  its  development.  Though  a goal  in  software 
development  is  transferability  (to  other  machines),  often  the  ineffi- 
ciencies that  can  result  are  too  costly  to  make  software  even  semi-inde- 
pendent. However,  these  dependencies  can  at  least  be  documented  to  aid 
transferabi 1 ity. 

METHOD  (MET):  describes  the  method  used  by  the  routine.  The 
METHOD  category  is  similar  to  the  ALGORITHM  category  but  may  contain 
more  information  about,  the  way  the  code  is  implemented.  For  example, 
the  routine  may  be  implementing  an  in-order  tree  traversal  algorithm, 
but  the  method  used  will  depend  on  the  tree  data  structure.  Since  FOR- 
TRAN is  not  recursive,  the  implicit  recursion  of  an  in-order  tree  tra- 
versal could  be  implemented  via  stacks  or  some  other  structure.  A 
METHOD  category  could  explain  how  the  algorithm  is  implemented. 

NONSYSTEM  EXTERNALS  (NON  SYS  EXT):  defines  the  various  routines 
used  by  the  system  that  are  not  part  of  the  system.  Much  of  this  infor- 
mation is  provided  by  ADS  for  CDC  systems.  However,  these  externals 
could  be  documented  in  this  category.  Also,  since  the  documentation 
files  represent  a static  version  of  the  actual  code  (i.e.  not  directly 
executable),  "dummy"  documentation  records  could  be  provided  for  those 
kind  of  externals.  Typically,  these  "dummy"  records  are  used  to  explain 
not  only  the  usage  of  the  externals,  but  also  why  these  externals  were 
chosen  over  similar  code  within  the  system  under  development. 

PURPOSE  (PUR):  describes  the  purpose  of  the  routine.  Often  the 
purpose  will  be  similar  to  the  method  used  in  the  routine.  (PURPOSE  may 
be  a bri of  description  of  a simple  method  whereas  the  METHOD  category 
would  provide  a det.ai  1 ed  description.) 

REFERENCES  ^nEF):  details  various  references  that  may  have  been 
used  in  developing  the  routine/system.  Another  reference  could  also  be 
the  system's  user  manual . For  example,  if  a complex  algorithm  cannot 
readily  be  explained  in  sufficient  detail  to  teach  the  user  about  it, 
references  are  included  to  indicate  where  the  user  can  obtain  more  in- 
formation about  the  algorithm  or  method. 

REMARKS  (REM):  details  any  documentation  which  did  not  fit  under 
other  categories;  for  example,  the  implementation  of  a finite  state  ma- 
chine in  the  code  or  the  tabular  information  of  states  and  transitions. 
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REVISED  (REV):  notes  revisions  made  to  the  code.  In  addition  to 
date  of  revision,  this  category  could  also  contain  the  name  of  and 
reason  for  the  revision. 

SYSTEM  (SYS):  denotes  the  system  of  the  code.  SYSTEM  can  refer  to 
either  the  software  development  system  (thus  indicating  the  LDCATIDN  of 
the  most  up-to-date  version  of  the  code)  or  the  operating  system  ex- 
pected by  the  programmer  (thus  indicating  an  inherent  IMPLEMENTATION 
DEPENDENCY). 

SYSTEM  DEPENDENCIES  (SYS  DEP):  denotes  possible  dependencies  of 
the  documented  system. 

TITLE  (TIT):  gives  the  title  of  the  routine.  Typically  the  title 
should  be  the  mnemonic  meaning  of  the  routine  name.  The  routine  name 
might  also  be  included  in  the  title  section.  For  example,  "CD  WRLFZB 
- WRITE  LOAD  FILE  ZONE  BLOCK"  could  be  the  title  line  for  routine 
WRLFZB. 

(Note:  if  the  word  preceding  the  "-"  is  the  name  of  a common 
block,  the  title  text  is  automatically  taken  to  be  the 
common  block  title.) 

For  example: 

CD  LFEHDR  - LOAD  FILE  ENVIRONMENT  HEADER  COMMON 
Additionally  COMMON  BLOCK  TITLE  (COM  TIT)  may  be  used  for  common  blocks. 

VARIABLE  DICTIONARY  (VAR):  defines  the  variables  in  the 
routine/common  block.  In  addition  to  indicating  the  usage  of  the 
variable,  a definition  might  also  indicate  valid  values  of  the  variable 
and  these  values'  meanings. 
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APPENDIX  B: 

ADS  USER  ERROR  MESSAGES 


If  these  messages  are  printed  during  an  ADS  execution,  the  user 
should  correct  some  of  his/her  input  or  bring  the  output  to  the  ADS  con- 
sultant. The  messages  are  of  three  types  --  WARNING,  SEVERE,  or  FATAL. 
WARNING  messages  are  informative  to  the  user;  SEVERE  messages  usually 
indicate  the  user  must  correct  something  in  the  code  or  input;  FATAL 
errors  indicate  that  the  ADS  system  has  an  unrecoverable  error.  SEVERE 
errors  in  the  input  commands  cause  abort  of  the  current  input  command. 

The  messages  are  listed  by  type;  each  description  includes  hints  to 
the  user  of  causes  and  corrections  of  ADS  errors. 


WARNING  Messages 

INVALID  NAME  ENTERED  — > name,  ILLEGAL  FOR  TYPE  -->  ROUTINE 

A name  in  the  <name  list>  of  a PRINT  commmand  cannot  be  found  on 
the  master  list  of  routines.  User  should  check  spelling,  make  sure  cor- 
rect documentation  files  are  attached,  or  check  SRCFL  and  REFFL  files  to 
ascertain  that  such  a routine  exists. 


INVALID  NAME  ENTERED  -->  name,  ILLEGAL  FOR  TYPE  -->  COMMON 

A name  in  the  <name  1 i s t > of  a PRINT  command  cannot  be  found  on  the 
master  list  of  common  blocks.  User  should  check  spelling,  make  sure 
correct  documentation  files  are  attached,  or  check  SRCFL  for  existence 
of  common  block  documentation. 


INVALID  NAME  ENTERED  — > name,  ILLEGAL  FOR  TYPE  — > REPORT 

A name  in  the  <name  1 i st > of  a PRINT  command  cannot  be  found  in  the 
master  list  of  reports.  User  should  check  spelling,  make  sure  correct 
documentation  files  are  attached,  or  check  previous  input  commands  for 
definition. 


NOT  FOUND  LIST  IS  FULL,  NO  MORE  CROSS-REFS  ALLOWED 

The  list  detailing  the  names  referenced  but  not  found  on  the  master 
files  is  full  (100  entries  allowed)  and  no  more  will  be  entered  into  the 
list.  This  list  is  output  as  a byproduct  of  a "PRINT  ...  FOR  ALL  .." 
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command.  If  this  message  occurs,  only  the  first  100  occurrences  will  be 
I istod. 


RESTARTING  PARSE  WITH  FOLLOWING  CARD. 

Parsing  of  the  source  code  will  resume  with  the  card  listed  after 
this  message.  User  should  check  SRCFL  and  REFFL  for  one  to  one  cor- 
respondence between  modules  and  reference  maps. 


ERROR  IN  READ  TAB,  SET  TO  NEAREST  --  1 OR  4 

The  number  of  indentation  levels  has  exceeded  the  limit  of  four. 
This  message  will  occur  during  report  processing.  User  should  check 
documentation  "CD"  cards  for  too  many  " "s. 


DUPLICATE  WRITE  REQUESTED  FOR  ROUTINE  - name  - REQUEST  IGNORED 

A routine  has  been  documented  twice  in  one  run.  Only  the  first 
will  be  retained  on  the  documentation  files.  User  should  check  SRCFL 
for  the  duplicate  occurrence. 


DUPLICATE  WRITE  REQUESTED  FOR  COMMON  - name  - REQUEST  IGNORE; 

A common  block  has  been  documented  twice  in  one  run.  Only  the 
first  will  be  retained  on  the  documentation  files.  User  should  check 
SRCFL  for  the  duplicate  documentation  occurrence. 


REQUESTED  READ  OF  RECORD  (ROUTINE)  — name,  RECORD  NOT  ON  MASTER  FILE 

A routine  documentation  record  has  been  referenced  and  retrieval 
has  been  attempted,  but  the  record  of  the  requested  name  is  not  on  the 
documentation  files.  For  example,  this  message  will  occur  for  externals 
that  are  part  of  the  FTN  library.  User  should  make  sure  correct  docu- 
mentation files  are  attached. 


REQUESTED  READ  OF  RECORD  (COMMON)  --  name,  RECORD  NOT  ON  MASTER  FILE 

A common  documentation  record  has  been  referenced  and  retrieval  has 
been  attempted,  but  the  record  of  the  requested  name  is  not  on  the  docu- 
mentation files.  User  should  make  sure  correct,  documentation  files  are 
attached  and  rerun  with  documentation  for  the  missing  common  block. 
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A was  expected  at  the  logical  end  of  the  statement  hut  was  not 
found  on  the  rest  of  the  card. 


MISSING  ASSUMED  PRESENT 
A was  expected. 


SEVERE  Messages 


MACRO  NAME  NOT  ON  MASTER  FILE  — > name 

A name  in  <report  1 i s t > of  a PRINT  command  cannot  be  found  on  the 
master  file.  User  should  check  spelling  or  make  sure  correct  documen- 
tation files  are  attached. 


UNKNOWN  KEYWORD  IN  DELETE  COMMAND 
The  format  of  the  user  DELETE  command  is  incorrect. 


MISSING  OR  MISPLACED  f IN  DELETE 
The  format  of  the  user  DELETE  command  is  incorrect. 


MISSING  ROUTINE  HEADER,  IGNORING  CARDS  STARTING  WITH 

A header  was  found  that  did  not  appear  to  be  a valid  FORTRAN  rou- 
tine header.  Cards  are  skipped  until  an  END  card  is  found  or  a valid 
routine  header  is  encountered. 


OVERFLOW  OF  STRING  BUFFER  ON  OUTPUT 

Some  combination  of  the  code  input  has  caused  the  string  buffer  to 
overflow  in  trying  to  create  a documentation  record.  Additional  infor- 
mation is  printed  that  will  be  useful  to  a consultant.  User  should 
bring  outputs  (ADS  execution,  listing  of  SRCFL)  to  an  APS  consultant. 


OVERFLOW  OF  STRING  BUFFER 


Additional  occurrences  of  the  above  error. 


TOO  MANY  VARIABLES  IN  COMMON  BLOCK  --  name 

The  common  block  displayed  has  too  many  variables  (limit  is  100) 
for  ADS.  Either  the  common  block  must  be  redefined  or  ADS  must  be 
changed . 


KEYWORD  EXPECTED 

A keyword  is  expected  in  the  current  input  command.  User  should 
check  the  command  for  proper  format. 


ROUTINE  NAME,  DEPTH,  OR  ; EXPECTED  AFltR  TREE 

A DRAW  command  has  improper  format.  User  should  check  the  command 
for  proper  format. 


DEPTH  EXPECTED 

The  DRAW  command  expects  a <DEPTH>,  but  found  something  entirely 
different.  User  should  check  command  for  proper  format. 


; EXPECTED 

A is  expected  in  the  current  input  command.  User  should  check 
the  command  for  proper  format. 


UNKNOWN  COMMAND 

The  current  input  command  cannot  be  recognized.  User  should  check 
input  command  for  proper  format. 


= EXPECTED  AFTER  REPORT  NAME 

A REPORT  input  command  has  improper  format.  User  should  check  the 
command  for  proper  format. 
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UNKNOWN  ERROR 


A REPORT  input  command  has  improper  format.  Ospr  should  check  the 
command  for  proper  format. 


DELIMITER  EXPECTED 

A REPORT  input  command  has  improper  format.  User  should  check  the 
command  for  proper  format. 


EXTERNALS  EXPECTED  AFTER  NON  SYSTEM 

A REPORT  keyword  was  not  properly  specified.  User  should  check  *hr 
command  for  format. 


SYSTEM  EXPECTED  AFTER  NON 

A REPORT  keyword  was  not  properly  specified.  User  should  check  the 
command  for  proper  format. 


FOUND  END-OF-FILF  WHILE  LOOKING  FOR  - character 

The  end  of  the  input  file  was  found  while  looking  for  the  indicated 
character. 


; FOUND  TOO  SOON  IN  PRINT  STATEMENT 

A terminated  the  PRINT  command  too  early.  User  should  check 
the  command  for  proper  format. 


MISSING  -FOR-  IN  PRINT  COMMAND,  SKIP  TO  ; 

The  FOR  keyword  was  missing  in  the  PRINT  command.  User  should 
check  the  command  for  proper  format. 

MISSING  END  CARD.  RESTART  WITH  FOLLOWING  CARD 

Parsing  of  the  source  code  will  resume  with  the  card  listed  after 
this  message.  User  should  place  an  END  card  in  SRCFL  before  the  listed 
card. 


ILLEGAL  NAME  IN  NAMELIST  FORMAT,  SKIP  TO  ; 

A word  which  could  not  be  a name  (i.e.,  a character,  etc.)  was 
found  in  a PRINT  command.  User  should  check  the  command  for  proper 
format . 


DEPENDENCY  EXPECTED 

The  word  DEPENDENCY  was  expected  in  a REPORT  keyword.  User  should 
check  for  proper  format. 


TOO  MANY  CHARACTERS  IN  TITLE,  SKIP  TO  ; 

The  TITLE  is  limited  to  80  characters.  User  should  check  the  TITLE 
card  to  make  sure  the  title  string  is  followed  by  a etc. 

FATAL  Error  Messages 

On  a FATAL  error,  the  indicated  messages  will  be  printed.  Also 
supplementary  information  of  use  to  the  consultant  will  be  printed.  All 
applicable  printouts  should  be  taken  to  the  consultant. 

TOO  MANY  ITEMS  IN  LIST  (ENTRNO) 

TOO  MANY  ITEMS  IN  LIST  (SCANNO) 

Too  many  items  have  been  entered  in  an  ADS  list.  The  items  in  the 
list  will  be  printed  as  part  of  the  error  dump. 

TOO  MANY  EXTERNALS  IN  ROUTINE 

The  limit  of  externals  used  by  one  routine  is  100. 

TOO  MANY  COMMONS  IN  ROUTINE 

The  limit  of  commons  used  by  one  routine  is  100. 

TOO  MANY  LOCAL  VARIABLES  IN  ROUTINE 

The  limit  of  local  variables  used  by  one  routine  is  100. 


APPENDIX  C: 


QUICK  REFERENCE  - ADS  USER  AND  CODE  INPUT 


ADS  User  Input 

Each  type  of  statement  listed  is  ended  by  a semicolon  Defi 

nitions  for  the  input  commands  are  listed  in  Chapter  3 and  4.  Charac- 
ters must  be  included  as  shown;  words  in  all  capitals 

must  be  included  as  shown. 


< I NPUT  KEYWORDS  ::=  ECHO  | NOECHO  | HELP  | END 

CADS  REPORT  DEFINES  REPORT  <NAMES  = <RFP0RT  SECTION  LISTS  ; 

<ADS  REPORT  DEFINES  ::=  REPORT  CNAMES  = <REPORT  SECTION  LISTS  ; 

<NAMES  ::=  (user  supplied  name  <=  10  characters) 

<REP0RT  SECTION  LISTS  ::=  <REP0RT  SECTION  NAMES 

[,  -REPORT  SECTION  NAME>] 

<REP0RT  SECTTON  NAMES  ::=  ALGORITHM  [ AUTHOR  | CALLED  I BY 

COMMON ( S ) [BLOCKS]  CALLED  | CONTROL  CARDS 
DATE  WRITTEN  | ENTRY  POINTS  I FILES  FLOW 
IMPLEMENTATION  DEPENDENCIES  | 

LOCATION  | MACHINE  DEPENDENCIES  | 

METHOD  | NON  SYSTEM  EXTERNALS  | 

PURPOSE  I REFERENCES  | REMARKS  | 

REVISED  | ROUTINES  CALLED  | SYSTEM 
SYSTEM  DEPENDENCIES  | TITLE  | 

VARIABLE  DICTIONARY 


<ADS  DELETES  ::=  DELETE  <RFCORD  TYPES  ( <NAME  LISTS  ); 

<RECORD  TYPES  ::=  ALL  | ROUTINE(S)  | COMMON(S)  | REPORT(S) 

<NAME  LISTS  ::=  <RECORD  NAMES  [,  <RECORD  NAMES  ] 

<RECORD  NAMES  ::=  (any  record  name  --  ROUTINE,  COMMON,  or  REPOPT) 

<ADS  PRINTS  PRINT  <REPORT  WIDTHS  <PAGI NG> 

( KREPORT  LISTS  ) FOR  <RECORD  LISTS; 

<RFPORT  WIDTHS  ::=  NARROW  | WIDE 

<PAGINGS  : :=  PAGED  [ UNPAGED 
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REPORT  L I ST > 


■NAME  LIST  OF  REPORT  names^ 


<RECORD  LIST > ::=  ALL  | ALL  ROUTINE(S)  | ALL  COMMON(S)  | 

ALL  REPORT(S)  I UPDATED  | UPDATED  ROUTINE(S) 
UPDATED  COMMON! S)  | ( « NAME  LIST>  ) 

<ADS  DRAWS  ::=  DRAW  <TREE  TYPES  <REPORT  WIDTHS  TREE  [<ROUTINE>] 
[<DEPTH>] 

<TREE  TYPES  ::=  COMPRESSED  | FULL 
<ROUTINES  ::=  (record  name  for  root  of  tree) 

<DEPTHS  ::=  (number  of  levels  to  be  drawn) 


ADS  Code  Input 


CDS  _ Begin  new  line  at  left  margin 

CDS  Begin  new  line;  retain  tab  setting  indicated  in  previous  line 

CD  No  new  line;  line  may  be  run  on  with  preceding  line 

CDS  Begin  new  line;  reset  tab  to  indent  5 spaces 

CDS  Begin  new  line;  reset  tab  to  indent  10  spaces 

CDS  Begin  new  line;  reset  tab  to  indent  15  spaces 

ADS  text,  sections  are  of  two  types: 

1.  Text  that  completely  documents  a section  --  <TYPE  1 TEXT> 

2.  Text  that  has  a subheader,  followed  by  a separator  character, 

followed  by  <TYPE  1 TEXT>  (reference  FILES,  VARIABLE  DICTIONARY  sec- 
tions). For  example:  "CD  TITLE : = RDIT  - PROGRAM  TO  READ  DECKS..." 
"RDIT  - PROGRAM  TO  ..."  is  <TYPE  1 TEXT>.  The  entire  statement  is  a 
TITLE  section.  In,  "CD  VAR1  - VARIABLE  TO  FLAG  ...",  "VAP1"  is  a 
subheader,  is  a separator.  "VARIABLE  TO  ..."  is  <TYPE  1 TEXT>.  A 
separator  character  is  typically  the  hyphen  but  may  be  any  of 

or 

The  ADS  sections  are  of  two  types: 

1.  ADS  type  1 section: 


CD  <TYPE  1 SECTION  HEADER) := 

CD  CTYPE  1 TEXT) 
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where  the  user  can  insert  multiple  "CO"  cards  of  CTYPE  1 TEXTS. 


2.  ADS  type  2 section: 


CD  CTYPE  2 SECTION  HEADERS 

CD  <TYPE  2 SECTION  SUBHEADERS  SEPARATORS 

CD  <TYPE  1 TEXTS 


where  <TYPE  1 TEXTS  cards  may  be  repeated  for  each  <TYPE  2 SECTION  SUB- 
HEADERS and  CTYPE  2 SECTION  SUBHEADERS  statements  may  also  be  repeated 
as  needed. 

<TYPE  1 SECTION  HEADERS  ::=  ALGORITHM  | AUTHOR  | CONTROL  CARDS  | 

COMMON  BLOCK  TITLE  | DATE  WRITTEN  ) FLOW  | 
IMPLEMENTATION  DEPENDENCIES  | 

LOCATION  | MACHINE  DEPENDENCIES  | 

METHOD  | NON  SYSTEM  EXTERNALS  1 
PURPOSE  I REFERENCES  | REMARKS  | 

REVISED  | SYSTEM  | 

SYSTEM  DEPENDENCIES  TITLE 

CTYPE  1 TEXTS  ;;=  <-TFXT  CARDS  CONTAINING  OPTIONS  "" 

CTYPE  2 SECTION  HEADERS  ::=  FILES  | VA 

CSEPARATORS  ::=  -(:[= 

CTYPE  2 SECTION  SUBHEADERS  ::=  < F I LE  OR  VARIABLE  NAME> 

(Note:  No  error  processing  is  done  during  the  parsing  of  the  "CD" 
cards.  Therefore,  an  invalid  section  header  or  section 
subheader  will  be  taken  as  text  of  the  previous  section. 
These  input  errors  will  usually  be  apparent  in  the  report 
output  by  making  some  documentation  categories  appear  in- 
consistent, or  a variable  thought  to  have  been  documented 
may  appear  with  a flag  indicating  no  documentation.) 
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APPENDIX  D: 


ADS  REFFL  INPUT  FILE  EXAMPLE 


This  appendix  illustrates  the  ADS  REFFL  input  file  for  the  example 
shown  in  Appendix  D.  Also  included  is  an  example  CDC  FTN  compiler  list- 
ing and  reference  map.  The  source  code  shown  is  the  APS  SRCFL  input, 
file. 
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JBIS  PABE  LS  BEST  QUALITY  PRACTICAL  1 
JJKM  OOM  NWUSHKD  ro  DDC'  * 


SBIS  PICE  IS  BBS!  QUALITY  PBACTI CABLE 
non  OOM  fUfUISHED  To  DDC  ' 


PROGPAm  WO  IT 


7*00_ 7*00  OPT*l 


FTN  4.6,452/034 


10 


IS 


20 


?5 


10 


35 


45 


50 


55 


PROGRAM  ROIT( INPUT, output, tape  1. TAPE?) 
implicit  INTEGER  (A-2) 

CO  TITLE:* 

CO  RDIT  - READ  A SET  OF  DECKS  TO  EXCLUDE  FROM  GENERAL  SORTING 

co  purpose : = 

CO  THE  PURPOSE  OF  THIS  PROGRAM  is  TO  GENERATE  MOVE  DIRECTIVES  TO 
CD  SORT  AN  OLDPl  --  UPOATE  LIBRARy.  uP  TO  THREE  LEVELS  OF 

CD  OF  CkS  CAN  BE  EXCLUDED  EROM  ThF.  TOTAL  SORT  (AND  AWE  THEN 

CO  SORTEO  AMONGST  THEMSELVES),  COMQECKS  ARE  SORTED  SEPARATELY 

CO  EROM  M&fN  DECKS.  EACH  LEVEL  MUST  ALSO  INPUT  A DECK  NAME 

CD  THAT  ALL  DECKS  IN  THE  LEVEL  W ILL  EOLLOW  — THE  DIRECTIVE 

CD  WILL  BE  OF  FORM? 

CUS_  — m0vE  <OECk  NAME>.<INPUT  DECK  NAME>" 

cos”  TO  LEVtL  DECKS  CnE  PUTS  IN  CARDS  OF  FORM: 

CDS COL  1--9.  NAME  OF  EXCLUDED  OECK 

CDS__  COL.  10  BLANK,  1,  OR  ? 

COi~  DECK  NAMES  ARE  SORTED  AND  MOVE  DIRECTIVES  GENERATED 
CD  SUCH  THAT  THE  FINAL  OROER  OF  IHE  UPDATE  OLDPL  WILL 
CD  RE  i 

CDS COMOECKS, 

CDS”0ECKS  (INPUT  CAPO  NAMES)  WITH  COL  10  = 1, 


CDS 
CDS 
c us 
CO 
CD 

CDS_ 

CD 

CO 

CD 

CD 

CD 

CD 

CD 

CD 

CD 

CD 

CO 

CD 

CO 

CO 

CD 


CD 

CD 

CD 

CD 

CO 

CD 

CD 

CD 

CD 

CD 


DECKS  ( I N ° U 7 CARD  NAMES)  WITH  COL  10  = 2, 

DECKS  (NOT  COMOECKS)  NOT  SPECIFIED  ON  INPUT  CAROS. 

NOTE  --  decks  (Input  card  names)  with  COL  10  = Blank 
ARE  NOT  SORTED!  THESE  DECKS  CAN  REMAIN  IN  PRESENT  PLACES 
IN  THt  OLOPL  ANO  BE  USED  FOR  POSITIONING  OTHER  DECKS. 

THE  PROGRAM  USES  The  BASIC  OUTPUT  (L=A14)  EROM  THE  UPDATE 
PROGRAM  as  INPUT  (TAPED. 

VARIABLE  DICTIONARY :* 

IN  - NUMBER  OF  INPUTS  <=  2*5. 

CDECK  - NUMBER  OF  COMMON  DECKS  IN  UPDATE  LIST. 

DECK A - NAME  OF  "AFTER"  OECK  FOR  CURRENT  LEVEL  (ON  OUTPUT). 

I - LOOP  CONTROL 

IKEY  - LEVEL  FOR  CURRENT  SORT. 

J - LOOP  CONTROL 

K - LOOP  CONTROL 

NCECK  - NUMpcp  or  DECKS  IN  LIST. 

COMMON/DECKS/DE  CKS(400),DFLAGS<400) 

COMMON  BLOCK  TITLE:* 

DECKS  - DECK  NAMES  AND  FLAGS 
VARIABLE  DICT I0nARy:= 

DECKS  - THE  array  OF  DECK  NAMES. 

PFIAGS  - THE  CORRESPONDING  ARRAY  OF  OECK  FLAGS  0--3 
DIMENSION  INMUF  (132), I NFLG ( 26fl ) 

COMMON  /SCRATCH/  SORTD(400) , INUM 

EQUIVALENCE  (SORTD ( 1 ) , INBUF ( l ) ) , (SORTD( 133) , INFLG( 1 ) ) 
COMMON  BLOCK  TITLE:* 

SCRATCH  - SCRATCH  USE  AREA. 

variable  dictionary:* 

SORTD  - AkRay  CONTAINING  NAMES  TO  BE  SORTED,  NUMBER  OF 
NAMES  IS  inum.- 

inbuf  - input  buffer  area  for  oeck  list  from  update. 

EQH1 valENCEO  TO  FIWST  PART  OF  SORTD  ARRAY. 

INFLG  - INPUT  Ot'CKS  AND  FLAGS. 

EOUIVALENCED  TO  PART  OF  SORTD  ARRAY. 

INUM  - NUMBER  OF  NAMES  TO  BE  SORTED  BY  ROUTINE  SORT. 
LOGICAL  ENOOK.ENOCDK 


IHIS  PAGE  IS  BEST  QUALITY  PRACTICABLE 
raoi  OOPY  rURAlSHED  TO  DLC 


PWO&WAM  non  7*>CO_7600  OKT»l 


FTN  *.6.<.S?/ 01<. 


60 


65 


70 


75 


HO 


85 


90 


95 


100 


105 


110 


C 


100 


105 

C 

C 

C 

C 

c 


110 


c 

c 


115 

C 

C 


120 

125 

126 


130 

C 

C 


135 


1*0 

1*7 

1*8 


0 A 1 A OtCKS*DFLAOS. 1NHUF , INF LG/ 1 20  0*0/ 

READ  INPUT 

PE* l NO  1 
IN  = l 

PFaO  700, INFlG ( ]N) 

if  if  of  i si.  input  ) .ne.  o>  oc  to  105 

IN  = IN  ♦ 1 

IF  (IN  .GT.  268)  STOP  “TOO  MANY  INPUTS" 

GO  TO  100 
IN  = IN  - 1 

depending  upon  list  option  to 

UPOATE,  HEAOEPS  OF  UP04TE  OUTPUT 
CAN  START  IN  COL  2 OR  COL  11. 

PEAD  (1.701)  InBijF 

IF  (tOF(l)  .NE.  0)  STOP  “ERROR  IN  DECK  LIST" 

LOOK  FOR  WORDS  — 

DECKS  ARE  LISTED  IN  ... 

IF  UNftuM?)  .EQ.  IrtD  .A.  I NBllF  ( 3 ) .EQ.  1 NE  .A. 

1 INrtUFU)  .EQ.  1 *-«C  .A.  IN«uF(5)  .EQ.  1 HK ) GO  TO  115 

IF  (iNfiijFUn  .EQ.  1H  .A.  INRUFU?)  .EQ.  lHO  .A. 

1 IN5UF(13)  .EQ.  1 HE  .A.  I NBUF ( 1 * ) .EQ.  1 HC 

2 .A.  INHL’F(IS)  .EQ.  1 HK ) GO  TO  115 
GO  TO  110 

CONTINUE 

PEADY  FOR  DECK  LIST 
READ  OECK  NAMES  (STARTING  IN  COL  11) 

READ  (1,701)  INBUF 

IF  (EOF ( 1 ) .NE.  o)  STOP  “ERROR  IN  DECK  LIST" 

IF  ( INBUF (11)  .NE.  lh  ) GO  TO  120 
GO  TO  115 
NDECK  = 0 

IF  (ENDDK (NDECK, INBUF ( 1 1 ) .P) ) GO  TO  130 
RE  AD ( 1 . 7 0 1 ) INBUF 

IF  <EOF(l)  .NE.  0)  STOP  “ERROR  IN  DECK  LIST" 

IF  (INBUF(I)  .EQ.  1 H 1 ) GO  TO  126 

GO  TO  1?5 

CONTINUE 

LOOK  FOR  COM  DECKS 

RE  AD  COMDECK  NAMES  (STARTING  IN  COL  ID 

READ  (1.701)  INBUF 

IF  (F  OF  ( 1 ) .NE . 0)  GO  TO  155 

IF  ( I NBUF ( 2 ) .EQ.  1 HC  .A.  I NBUF ( 3 ) .EQ.  1HO  .A. 

1 IN-VJF(A)  .EQ.  1 HM ) GO  TO  135 

IF  ( I Nrfi JF ( 1 1 ) .£0.  JH  .A.  InBuF (12)  .EQ.  1 HC  .A. 

1 INHUF(13)  .EQ.  1 hO  .a.  INBuF(1*)  .EQ.  1 HM ) GO  TO  135 

GO  TO  1 30 

PfAQ ( I » 70  D INBUF 

IF  (FOF(l)  .NE.  0)  STOP  “ERRCP  IN  DECK  LIST" 

IF  (InHUF(H)  .NE.  in  ) GO  TO  1*0 
GO  TO  135 
CONTINUE 
CDECK  = 1 

IF  (ENDCOK (NOECK , INBUF (D ) .8.C0ECK) ) GO  TO  155 
RE  AD ( 1 , 70  1 ) INBUF 

IF  ( EOF ( 1 ) .NE.  0)  STOP  "ERROR  IN  DCCK  LIST" 
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PROGRAM  RUIT  7500.7600  OPT*l 


1)5 


120 


125 


no 


1 15 


no 


ns 


ISO 


155 


no 


IF  (INBUF(l)  .tQ.  1H1)  GO  TO  li.S 
GO  TO  n7 
155  CONTINUE 


C 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 

c 


IF  ANY  INPUT  NAMES  WERE  accepted. 

THtY  APE  POSITIONED  In  A level  TO  BE 
USED  later  In  sorting. 

INTERNAL  VALUES  (STORED)  IN  DFlAGS  ARE! 

CARD  COL.  10  = 1.  DFlagS=1 

CARD  COL.  10  = 2.  DFLAGS=2 

CARO  COL.  10  = BLANK,  0FLAGS=5 

COMCECK.  DELAGSrJ 

OTHER  DECK.  DFLAGS=0. 

SORTING  IS  OONE  0.  1.2.  3.  IN 
DESCENDING  ORDER  IN  ORDER  TO  POSITION  THE 
DECKS  PROPERLY  WITH  THE  MOVE  STATEMENTS. 


IF 

UN  .EO,  0)  GO  TO 

170 

DO 

160  I = 1 .NDECK 

DO 

160  J- 1 , IN 

IF 

(AND (DECKS  < I 1 .MASK (Sm)  ) 

• NE. 

AND ( INFLG (J) .MASK (55) ) ) 

1 

GO  TO  160 

IF 

(ANDC1NFLGU)  • 77H ) 

.EO. 

1R  ) 

DFLAGS ( I ) *5 

IF 

(AND ( INFLG ( J) .778) 

.EO. 

IR 1 > 

DFLAGS l I ) = 1 

IF 

(AND(INFlGU)  .778) 

.EO. 

IK?) 

DFLAGS ( I ) =2 

160 

CONTINUE 

170 

CONTINUE 

PtflNT  702 

7 0<? 

format  ( 1 HI  .no, "GENERATING 

UPDATE  DIRECTIVES") 

DO  no  I = )n 


IKE  Y=  I - I 


IN(!M=0 


do  no  k = i,noeck 

no  IE  (DELAGS(K)  .EO.  IKEY)  CALI  SORT  IN  (OECKS  <K ) ) 

if  (inum  .to.  „i  go  to  no 

PE AO  700.0ECKA 

IE  It'OE  (5LINPUT)  .NE.  0)  DECKA  = lOHYANKSSt 


PRINT  703.0ECKA 

703  Format  ( Ih-,  ••  DIRECTIVES  WILL  BE  OF  FORM  ••MOVE  <DECK  NAME  > • " * 
1 »1  n,M  •••) 
call  sort 
call  smuutioecka) 
no  continue 

PEwINO  2 

700  E OPR at ( A 1 0 ) 

701  EOPMATl 132A1 ) 

STOP 

End 


symbolic  REFERENCE  map  |R  = 3) 

entry  POINTS  DEF  line  REFERENCES 

5212  ROI T 1 
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PSOGtfA*  P0IT  ?h00_7600  CPT=  1 FTN  4.6.45JVC14 


f»-  m *-+  cc  x>  no  © 

r"->  n ^ IP  l/' 


UJ  UJ  UJ 

C Q Q 


-3  «7> 

O u <t  p-  r-  i/i  rn  %c  1/1  X O 

j Z LOrt  «C  • — — f'  -4  ^ >4 


«c 

o 


UJ 

o 


UJ  ^ ^ N 

-4  * >r  o — O r~  Z J r 


u u. 

UJ  UJ 

O Q 


nJ 

Q 


O' 

cr 


U IT  4 ^ f ^ uj 
/ ^ ^ J ^ -J  «’ 


O 4> 

44'C10,'CVl'CuJlV4 
— f\J 


u 

UJ 


f\J 

CP 


O 


o 


o 


Tmssxrz 
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PROGRAM  RD1T 


7600.7600  OPT  * 1 


FTN  4.6.4S2/034 


STATEMENT  LABELS 

OEF  LINE  references 

0 

1^0 

1S6 

143 

148 

431? 

700 

FMT 

1 SB 

62 

14S 

431*. 

701 

FMJ 

1 S9 

73 

86 

4 ?*? 

70? 

FMT 

14? 

1M 

4301 

703 

FMT 

IS? 

1S1 

COMMON 

BLOCKS 

lfng  t h 

MEMBERS 

- BIAS  NAMF (LENGTH) 

ne.c*s 

soo 

0 DECKS  (400) 

SCRATCH 

*01 

0 SOWTD  (400) 

euuiv 

CLASSES 

length 

members 

. BIAS  NAME (LENGTH) 

SOTO 

SOB  1 D 

400 

0 1NBUF  (132) 

<.00  OFLAGS  (400) 
400  INUM  111 


132  1NFLG  1268) 


STATISTICS 

PROGRAM  length 

BUFFER  LENGTH 

SCH  LABELED  common  LENGTH 


1689  117 
4?0»H  2180 
22618  1201 


FNDDK  - FUNCTION  VALUE  < WHEN  TRUE*  ENO  OF  DECK  LIST 


ffeis  PAGE  IS  BEST  QUALITY  PRACTICABLE 

PROJI  oorx  jurjulshhd  to  ddq  : 

FUNCTION  ENOOK 

7600_7fe00 

ORT*  1 

FTN  6. <.52/0  34 

ST  A Tt. MEN  T LABE  LS 

otf  line 

REFERENCES 

o mo 

30 

21 

o -on 

32 

26 

13  700  Fmt 

?S 

2« 

common  “locks  length 

mEmhE  RS  - 

BIAS  NAME(LENGTH) 

CFCKS  300 

0 

DECKS  IO00) 

000  DFLAGS  UOOl 

statistics 

PPOOWAM  LFNGTM 

308 

2<* 

SCM  L&-LLEO  COMMON  LENGTH 

lAAOfl 

BOO 

E 


K>IS  N» 15 


function  enocdk  7^no_7^oo  opt»i 


ftn  4.6*452/034 


i 


s 


10 


IS 


?0 


25 


30 


35 


CO 

CO 

CO 

CO 

Cl) 

Cl) 

CO 

CO 

CO 

CO 

CO 

CO 

CO 

CO 

CO 


700 


101 

100 

400 


LOGICAL  FUNCTION  ENDCOK (NOECK , INBUF .N .COECK ) 

IMPLICIT  I NT  EGE  R ( A- 7 ) 

TITLE. •=  ENDCOK  - Dfc  TtRMINE  END  OF  CO»DECK  LIST 

purpose : = this  function  determines  when  the  eno  of 

COM OECK  LIST  HAS  BEEN  REACHED.  IT  ALSO  DECODES  THE  LINE 
OF  INPUT  INTO  THE  COMUfCK  LIST  TO  BE  SORTED. 

VAR : = 


CDECk  - STARTING  POSITION  FOR  COmDECks. 

ENDCOK  - FUNCTION  VALUE.  WHEN  TRUE.  END  OF  COMUECK  LIST 

I - LOOP  CONTROL. 

INBUF  - INPUT  LINE  (INPUT  PARAMETER), 

I]  - START  CHARACTER  POSITION  OF  DECK  NAME 

I?  - FND  CHARACTER  POSITION  OF  DECK  NAME 

J - LOOP  CONTROL 

N - NUMBER  OF  DECK  NAMES  ALLOWED  IN  A LINE. 

NDECK  - CURRENT  TOTAL  NUMBER  OF  DECKS. 

WORD  •-  WOO  FOUND  II. .12  POSITIONS.  IF  BLANK  END  OF  LIST. 
DIMENSION  INHUE ( 1 ) 

CQMMGN/UECKS/DECKS (400) .OFLAGS (400) 

FnOCDK=.F alse . 


DO  100  1=1, N 

11  = 1 1-1  ) MOM 

12  = 11*9 

ENCODEC10.700.wORD)  (INBUF(J) ,J=I1 .12) 
FORMAT ( 1 0A1 ) 

IF  (WORD  .EG.  10H  ) GO  TO  400 

DO  101  J=CDECK, NOECK 

IF  (DECKS ( J)  ,N£.  WORD)  GO  TO  101 

COECk=j 

OFLAGS ( J ) =3 

GO  TO  100 

CONTINUE 

CONTINUE 

RETURN 

EnOCO*  = .TRUE. 

RFTURN 

END 


CA *0  NR.  SEVERITY  DETAILS  DIAGNOSIS  OF  PROBLEM 

29  I COECK  THIS  STATEMENT  REDEFINES  A CURRENT  LOOP  CONTROL  VARIABLE  OR  PARAMETER. 


SYMBOL  I C REFERENCE  map  (R  = 3> 


ENTRr  POINTS 

OEF  LINE 

references 

4 ENDCOK 

l 

34  16 

variables 

SN  TrPE 

RELOCATION 

0 COECK 

INTEGER 

F.P. 

SEFS 

27 

DEFINED 

0 decks 

INTEGER 

ARRAY  OECKS 

HEFS 

19 

28 
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SUBROUTINE  SHOUT  7600_7600  OPT=»l 


COMMON  BLOCKS  LENGTH 
SCRATCH  401 


MEMBERS  - BIAS  NAME  <LENGTH) 
0 SORTO  (400) 


STATISTICS 

PROGRAM  LENGTH  4SB  3T 

SCM  LABELED  COMMON  LENGTH  621B  401 


TTN  4.*.45.V014 
400  INUM  <1> 
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SUBROUTINE  SOKIO  760 0_ 7600  GPT  = 1 FTN  A.6»6S2/03<* 


1 SUBROUTINE  SOBTO 

implicit  integer ia-zi 

COmmON/SCRaTCH/SORTOUOO)  ,INUM 
INLMsO 

5 RETURN 

END 


SYMBOLIC 

REFERENCE 

MAP  (R  = 3) 

ENTRY  PCIMS 

OFF  LINE 

REEk  PENCES 

I SO® TO 

1 

5 

VAPIAHLFS  SN 

type 

RELOCATION 

N20  INU* 

TNTtGFP 

SCRATCH 

REES 

3 

OEFINEO 

0 SOPTD 

INTEGER 

ARRAY  SCRATCH 

REES 

3 

common  blocks 

LENGTH 

MEMBERS  - BIAS  NAME (LENGTH) 

SCRATCH 

40] 

0 SORTO 

(400) 

400 

INUH  (1 

STATISTICS 

PROGRAM  LENGTH  2B  ? 

SCM  LABELED  common  LENGTH  62 1 B A01 
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APPENDIX  E: 


ADS  EXECUTION  EXAMPLE 


This  appendix  illustrates  a complete  ADS  execution.  Pages  titled 
"CiRL  - ADS  - MESSAGE"  show  the  user  input  and  any  warning,  severe  or 
fatal  messages  produced  by  ADS.  The  remaining  pages  display  the  result 
of  the  user  input. 
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CERL  - AOS  - VERSION  1.0 
AOS  USER  MANUAL  EXAMPLE 


PAGE 

AS  OF  4 MAY  78-ROIT 


I _SORT IN 
I SORT 
I SMOUT 

Teof 

I ENDOK 

i'enocok 
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04  MAY  78 
DUMP 


12.06.S8  CERL  - ADS  - VERSION  1.0  PAGE  1 

AOS  USER  MANUAL  EXAMPLE 

AS  OE  4 MAY  78-RDIT 


TITLE.  i 

RDIT  - REAO  A SET  OE  DECKS  TO  EXCLUDE  FROM  GENERAL  SORTING 
PURPOSE. 

THE  PURPOSE  OF  THIS  PROGRAM  is  TO  GENERATE  ^OvE  DIRECTIVES  TO 
SORT  AN  OLOPL  --  UPDATE  LIBRARY.  UP  TO  THREE  LEVELS  OF  DECKS  CAN  BE 
EXCLUDED  FROM  THE  TOTAL  SORT  (AND  ARE  THEN  SORTED  AMONGST 
THEMSELVES).  COMOECKS  ARE  SORTED  SEPARATELY  FROM  MAIN  DECKS.  EACH 
LEVEL  MUST  ALSO  INPUT  A DECK  NAME  THAT  ALL  DECKS  IN  THE  LEVEL  W ILL 
FOLLOW  --  THE  DIRECTIVE  WILL  PE  OF  FORM; 

"»MOVE  <OECK  NAME>,< INPUT  DECK  NAME>" 

TO  LEVEL  DECKS  ONE  PUTS  IN  CAROS  OE  FORM: 

COL  1 — 9.  NAME  OF  EXCLUDED  DECK 
COL.  10  BLANK,  1 , OH  2 

DECK  NAMES  ARE  SORTED  AND  MOvE  DIRECTIVES  GENERATED  SUCH  THAT  THE 
FINAL  ORDER  OF  THE  UPDATE  OLOPL  WILL  BE: 

COMOECKS. 

DECKS  (INPUT  CARD  NAMES)  WITH  COL  10  = 1, 

DECKS  (INPUT  CARD  NAMES)  WITH  COL  10  = 2. 

DECKS  (NOT  COMDECKS)  NOT  SPECIFIED  ON  INPUT  CARDS. 

NOTE  — OECKS  (INPUT  CARD  NAMES)  WITH  COL  10  = BLANK  ARE  NOT 
SORTED!  THESE  DECKS  CAN  REMAIN  IN  PRESENT  PLACES  IN  TH£  OLDPL 
AND  BE  USED  FOR  POSITIONING  OTHER  DECKS. 

THE  PROGRAM  USES  THE  BASIC  OUTPUT  <L=A14)  FROM  THE  UPDATE  PROGRAM  AS 
INPUT  (TAPED. 

VARIABLE  DICTIONARY  FOR  ROUTINE  RDIT 

COECK  - NUMBER  OF  COMMON  DECKS  IN  UPDATE  LIST. 


OECKA  - NAME  OF  "AFTER"  OECK  FOR  CURRENT  LEVEL  (ON  OUTPUT). 

I - LOOP  CONTROL 

IKEY  - LEVEL  FOR  CURRENT  SORT. 

IN  - NUMBER  OF  INPUTS  <=  268. 


J - LOOP  CONTROL 

K - LOOP  CONTROL 

NDECK  - NUMBER  OF  DECKS  IN  LIST. 


THIS  A MAIN  PROGRAM  OF  LENGTH  117  WORDS. 
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PAGE 


OU  HAY  78  12.06.58  CERL  - AOS  - VERSION  1.0 

ADS  USER  MANUAL  EXAMPLE 
0uMp  *5  OF  4 MAY  78-ROIT 


ROUTINES  CALLED  By  RDIT  ARE  — 

ENDCDK  ENQDK  EOF  SMOUT  SORT 

AND  MASK 


SORTIN 


COMMON  BLOCKS  CALLED  BY  RDIT 
DECKS  SCRATCH 


ARE  — 


THE  ROUTINES  WHICH  CALL  RDIT  ARE  — •«  NONE  «* 


THIS  PACE  IS  BEST  QUALITY  FRACTICABI* 

yacm  cxxpy  /ukhishjsd  id  ldc  — - 

OA  MAY  78  12.06.58  CERL  - ADS  - VERSION  1.0  PAGE  3 

ADS  USER  MANUAL  EXAMPLE 

DUMP  AS  OF  A MAY  78-ENLCDK 

TITLE. 

ENDCDK  - DETERMINE  END  OE  COMOECK  LIST 
PURPOSE. 

THIS  FUNCTION  DETERMINES  WHEN  THE  END  OF  COMOECK  LIST  HAS  BEEN 
REACHED.  IT  ALSO  DECODES  THE  LINE  OF  INPUT  INTO  THE  COMOECK  LIST  TO 
BE  SORTED. 

VARIABLE  DICTIONARY  FOR  ROUTINE  ENDCDK  . 

CDECK 
ENDCDK 

I 

I N8UF 

II 
12 
J 
N 

NDECK 
WORD 

THIS  IS  A LOGICAL  FUNCTION  OF  LENGTH  21  WORDS. 

ROUTINES  CALLED  By  ENDCDK  ARE  — »*  NONE  ** 

COMMON  BLOCKS  CALLED  BY  ENOCOK  ARE  — 

DECKS 

THE  ROUTINES  WHICH  CALL  ENDCDK  ARE  -- 

ROI  T 


- STARTING  POSITION  FOR  COMOECKS. 

- FUNCTION  VALUE,  WHEN  TRUE,  END  OE  COMOECK  LIST 

- LOOP  CONTROL. 

- INPUT  LINE  (INPUT  PARAMETER). 

- START  CHARACTER  POSITION  OE  DECK  NAME 

- END  CHARACTER  POSITION  OF  DECK  NAME 

- LOOP  CONTROL 

- NUMBER  OE  DECK  NAMES  ALLOWED  IN  A LINE. 

- CURRENT  TOTAL  NUMBER  OE  DECKS. 

- WORD  FOUND  II. .12  POSITIONS,  IF  BLANK  END  OF  LIST. 
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ADS 

CERL  - ADS  - VERSION  1.0 

USER  MANUAL  EXAMPLE 

RAGE 

DUMP 

AS  OF  4 MAY 

78-ENOOK 

TITLE. 

ENOOK  - DETERMINE  END 

PURPOSE. 

OF 

DECK  LIST 

THIS  FUNCTION  DETERMINES  WHEN  THE  END  OF  DECK  LIST  HAS  BEEN  REACHED. 
IT  ALSO  DECODES  THE  LINE  OF  INPUT  INTO  THE  DECK  LIST  TO  BE  SORTED. 

VARIABLE  DICTIONARY  FOR  ROUTINE  ENDDK  . 

ENDDK  - FUNCTION  VALUE,  WHEN  TRUE.  END  OF  OECK  LIST  HAS  BEEN 
REACHEO. 

I - LOOP  CONTROL. 

INBUF  - INPUT  LINE  (INPUT  PARAMETER). 

II  - START  CHARACTER  POSITION  OF  DECK  NAME 

12  - END  CHARACTER  POSITION  OF  OECK  NAME. 

J - LOOP  CONTROL. 

N - NUMBER  OF  POSSIBLE  DECKS  ON  THIS  LINE  (INPUT 

PARAMETER) . 

NDECK  - CUMULATIVE  COUNT  OF  NUMBER  OF  OECKS  (I/O  PARAMETER). 
WORD  - WORD  FOUND  II. .12  POSITIONS,  IF  BLANK  ENO  OF  LIST. 
THIS  IS  A LOGICAL  FUNCTION  OF  LENGTH  24  WORDS. 

ROUTINES  CALLED  BY  ENDDK  ARE  — **  NONE  ** 

COMMON  BLOCKS  CALLED  BY  ENDDK  ARE  -- 

DECKS 

THE  ROUTINES  WHICH  CALL  ENDDK  ARE  — 

RDIT 
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IP.0A.S8  CERL  - ADS  - VERSION  1.0  PAGE 

ADS  USER  MANUAL  EXAMPLE 

AS  OF  4 MAY  78-SMOUT 


TITLE  . 

SMOUT  - OUTPUT  THE  SORTED  NAMES  IN  UPDATE  DIRECTIVE  FORM. 

PURPOSE. 

THIS  ROUTINE  OUTPUTS  THE  SORTED  NAMES  (ON  T APE?)  IN  UPDATE  DIRECTIVE 
FORM  (*MOvE  ...). 

VARIABLE  DICTIONARY  FOR  ROUTINE  SMOUT  . 

DECKA  - DECK  AFTER  WHICH  CURRENT  LEVEL  OE  SORTED  NAMES  IS  TO 
BE  PLACED. 

I - *°  NONE  * 

J - **  NONE  ** 

K - **  NONE  * 

NAME  - OECK  NAME  IN  CHARACTER  FORMAT.  SINCE  UPDATE  CAN 

NOT  ACCEPT  BLANKS  BEFORE  THE  COMMA  IN  THE  "MOVE 
DIRECTIVE. 

THIS  SUBROUTINE  HAS  A LENGTH  OF  37  WORDS. 

ROUTINES  CALLED  BY  SMOUT  ARE  --  NONE  ** 

COMMON  BLOCKS  CALLED  BY  SMOUT  ARE  — 

SCRATCH 

THE  ROUTINES  WHICH  CALL  SMOUT  ARE  — 


ROI  T 


ISIS  PAGE  LS  BEST  QUALITY  PRACTICABL1 
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ADS  USER  MANUAL  EXAMPLE 

DUMP  AS  OF  4 MAY  78-SOWT 


TITLE. 

SORT  - SORT  A LIST  OF  NAMES 
REFERENCES. 

KNUTH,  VOL  III:  SEARCHING  AND  SORTING: 

ELSON,  DATA  STRUCTURES? 

MANY,  MANY  MORE. 

METHOD. 

THE  METHOD  OF  THIS  SORT  IS  A SELECTION  SORT.  AT  EACH  STEP  THE  ITEM 
WITH  THE  HIGHEST  (LOWEST)  VALUE  IS  SELECTED  FROM  THOSE  REMAINING. 

PURPOSE. 

THIS  ROUTINE  ACCOMPLISHES  THE  ACTUAL  SORT  ON  THE  INPUT  LIST  OF  NAMES. 
THE  LIST  IS  SORTED  IN  DESCENDING  ORDER  SO  THAT  THE  EVENTUAL  OUTPUT 
WILL  PLACE  THE  DECKS  ON  THE  OLOPL  IN  PROPER  ORDER. 

VARIABLE  DICTIONARY  FOR  ROUTINE  SORT 

I - LOOP  CONTROL 

II  - LOOP  CONTROL  (1*1) 

J - LOOP  CONTROL 

K - LOOP  CONTROL 

KEY  - CURRENT  KEY 

N 1 - LOOP  CONTROL  (NUMBER  OF  DECKS  - 1) 

THIS  SUBROUTINE  HAS  A LENGTH  OF  8 WORDS. 

ROUTINES  CALLED  BY  SORT  ARE  — *<*  NONE  ** 

COMMON  BLOCKS  CALLED  BY  SORT  ARE  -- 
SCRATCH 

THE  ROUT  I NE.S  WHICH  CALL  SORT  ARE  — 

RDIT 
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ads  user  manual  example 

Dump  as  of  a may  78-soriin 


TITLE. 

SOWTIN  - INPUT  NAMES  TO  HE  SORTED. 

PURPOSE. 

THIS  ROUTINE  IS  CALLED  ONCE  FOR  EACH  NAME  TO  HE  SORTED.  THIS  ROUTINE 
ACCUMULATES  THOSE  NAMES  INTO  A SORT  LIST. 

VARIABLE  DICTIONARY  FOR  ROUTINE  SORTIN  . 

DECKN  - DECK  NAME  TO  BE  PLACED  IN  LIST  (INPUT  PARAMETER). 

THIS  SUBROUTINE  HAS  A LENGTH  OF  8 WORDS. 

ROUTINES  CALLED  BY  SORTIN  ARE  — **  NONE  ** 

COMMON  BLOCKS  CALLED  BY  SORTIN  ARE  — 

SCRATCH 

THE  ROUTINES  WHICH  CALL  SORTIN  ARE  — 


ROIT 


UH1S  PACE  IS  BEST  QUALITY  PRACTICABL1 
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OA  MAY  78  12.06.58  CERL  - AOS  - VERSION  1.0  PAGE  8 

ADS  USER  MANUAL  EXAMPLE 

DUMP  AS  OF  4 MAY  78-SORT 0 

VARIABLE  DICTIONARY  fOR  ROUTINE  SORTO  — **  NONE  ** 

THIS  SUBROUTINE  HAS  A LENGTH  OF  2 WORDS, 

ROUTINES  CALLED  By  SORTO  ARE  — **  NONE  ** 

COMMON  BLOCKS  CALLED  BY  SORTO  ARE  — 

SCRATCH 

THE  ROUTINES  WHICH  CALL  SORTO  ARE  — **  NONE  ** 


miS  PAGE  IS  BBS!  QUALITY  FRACIICABL§ 
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AOS  USER  MANUAL  EXAMPLE 

CROSS-REF 

AS  OF  4 MAY  78-SORT 0 


PAGE  9 


EOF 


THE  FOLLOWING  RECORDS  WERE  NOT  FOUND  ON  THE  MASTER  FILE  


ROIT 


THE  ROUTINES  which  CALL  EOF  ARE  
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04  MAY  78  12.06.58  CERL  - AOS  - VERSION  1.0  PAGE  10 

ADS  USER  MANUAL  EXAMPLE 

OUMP  AS  OF  4 MAY  78-DECKS 


TITLE. 

DECKS  - DECK  NAMES  ANO  FLAGS 

VARIABLE  DICTIONARY  FOR  COMMON  BLOCK  DECKS  . 

DECKS  - THE  ARRAY  OF  DECK  NAMES • 

OFLAGS  - THE  CORRESPONDING  ARRAY  OF  DECK  FLAGS  0--3 

THE  ROUTINES  WHICH  CALL  DECKS  ARE  -- 
RDIT  ENDDK  ENDCDK 


THIS  PAGE  IS  BEST  QUALITY  PRACTICABL* 
JBOJI  OOPY  FUffCilSriEL  TO  UDC  — - 


OA  MAY  78  12.06.58  CERL  - AOS  - VERSION  1.0  PAGE  11 

ADS  USER  MANUAL  Example 

Rump  as  of  a may  7h-scratch 

TITLE. 

SCRATCH  - SCRATCH  USE  AREA. 

VARIABLE  DICTIONARY  FOR  COMMON  BLOCK  SCRATCH. 

INBUF  - INPUT  BUFFER  AREA  FOR  DECK  LIST  FROM  UPDATE. 

EOUl VALENCED  TO  FIRST  PART  OF  SORTD  ARRAY. 

INFLG  - INPUT  DECKS  AND  FLAGS.  EQUIVALENCES)  TO  PART  OF  SORTD 
ARRAY. 

INUM  - NUMBER  OF  NAMES  TO  BE  SORTED  BY  ROUTINE  SORT. 

SORTD  - ARRAY  CONTAINING  NAMES  TO  BE  SORTED,  NUMBER  OF 

NAMES  IS  INUM. 

THE  ROUTINES  WHICH  CALL  SCRATCH  ARE  — 

ROIT  SMOUT  SORTO  SORTIN  SORT 


fflIS  PAGE  IS  BEST  QUALITY  PRACIICABIJI 
oqpy  jtjrsished  to  doc 
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ADS  USER  MANUAL  EXAMPLE 

OFEINlTION  AS  OF  U MAY  78-A8STRACT 


REPORT  AHSTPACT  PRINTS  THE  FOLLOWING  SECTIONS 
IN  THE  ORDER  LISTED 


TITLE 

AUTHOR 

PURPOSE 

METHOD 

ALGORITHM 

REFERENCES 
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04  MAY  78  12.0ft.S8  CERL  - AOS  - VERSION  1.0  PAGE  13 

AOS  USER  MANUAL  EXAMPLE 

DEE  I N I T I ON  AS  OF  4 MAY  78-DUMP 


REPORT  DUMP  PRINTS  THE  FOLLOWING  SECTIONS 

IN  THE  ORDER  LISTED 


TITLE 

AUTHOR 

DATE  WRITTEN 
REFERENCES 
LOCATION 
METHOD 

CONTROL  CARDS 

REMARKS 

SYSTEMS 

PURPOSE 

ALGORITHM 

DATE  REVISED 

NON  SYSTEM  EXTERNALS 

MACHINE  DEPENDENCIES 

SYSTEM  DEPENDENCIES 

IMPLEMENTATION  DEPENDENCIES 

FLOW 

FILES 

VARIABLE  DICTIONARY 

I ODUM 

ENTRY  POINTS 
ROUTINES  CALLED 
COMMON  BLOCKS  CALLED 
CALLED  BY  ROUTINES 
I ODUM 1 ( I ) 

I ODUM  1 (2) 

I ODUM  1 (3) 

IOOUMl (4) 

I ODUM  1 (5) 

I ODUM  1 (6) 
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04  MAY  78  12.08.S8  CERL  - AOS  - VERSION  1.0  PAGE  14 

AOS  USER  MANUAL  EXAMPLE 

TITLES  AS  OF  4 MAY  78-**«**«»** 


TITLE. 

RDIT  - RE AO  A SET  OF  DECKS  TO  EXCLUDE  FROM  GENERAL  SORTING 

TITLE. 

ENDCDK  - DETERMINE  END  OF  COMDECK  LIST 
TITLE. 

ENDDK  - DETERMINE  END  OF  DECK  LIST 
TITLE. 

5MOUT  - OUTPUT  THE  SORTED  NAMES  IN  UPDATE  DIRECTIVE  FORM. 
TITLE. 

SORT  - SORT  A LIST  OF  NAMES 
TITLE. 

SORTIN  - INPUT  NAMES  TO  BE  SORTEO. 


r 


THIS  PAGE  IS  BEST  QUAL I T^PRACI ICABL1 
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04  MAY  78  12.06.58  CERL  - AOS  - VERSION  1.0  PAGE  IS 

AOS  USER  MANUAL  EXAMPLE 

CROSS-REF  45  OF  U may  78-*»° ** »*oo o 


THE  FOLLOWING  RECORDS  WERE  NOT  FOUND  ON  THE  MASTER  FILE  

EOF 


THE  ROUTINES  WHICH  CALL  EOF  ARF  -- 

RDIT 


- 


^2EaESr3W?S, 


-v„ 


was  PAQK  IS  BEST  QUALITY  PRACIIQA&*! 
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04  MAY  78  12.06.58  CERL  - ADS  - VERSION  1.0 

ADS  USER  MANUAL  EXAMPLE 

TITLES  AS  OE  4 MAY  78- 


TITLE. 

DECKS  - DECK  NAMES  AND  FLAGS 
TITLE. 

SCRATCH  - SCRATCH  USE  AREA. 


PAGE  16 
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OA  MAY  78  12.06.S8  CERL  - AOS  - VERSION  1.0  PAGE  17 

AOS  USER  MANUAL  EXAMPLE 

DEFINITION  AS  OF  A MAY 


REPORT  ABSTRACT  PRINTS  THE  FOLLOWING  SECTIONS 
IN  THE  ORDER  LISTED 


TITLE 

AUTHOR 

PURPOSE 

METHOO 

ALGORITHM 

REFERENCES 


' 


[ 
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AOS  USER  MANUAL  EXAMPLE 

DEE  INI T ION  AS  OF  4 MAY  78-***«***»** 


REPORT  DUMP  PRINTS  THE  FOLLOWING  SECTIONS 

IN  THE  ORDER  LISTED 


TITLE 

AUTHOR 

DATE  WRITTEN 
REFERENCES 
LOCATION 
METHOD 

CONTROL  CARDS 

REMARKS 

SYSTEMS 

PURPOSE 

ALGORITHM 

DATE  REVISED 

NON  SYSTEM  EXTERNALS 

MACHINE  DEPENDENCIES 

SYSTEM  DEPENDENCIES 

IMPLEMENTATION  DEPENDENCIES 

ELOW 

FILES 

VARIABLE  DICTIONARY 
I ODUM 

ENTRY  POINTS 
ROUTINES  CALLED 
COMMON  BLOCKS  CALLEO 
CALLED  BY  ROUTINES 

IODUM 1 ( I ) 

I ODUM  1 (2) 

I ODUM  1 (3) 

I0DUM1 (4) 

I ODUM  1 (5) 

IODUM 1 (6) 
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OF  MAy  ^ooo 

REPOPT  TITLES  PRINTS  THE  FOLLOWING  SECTION 
IN  THE  OROEP  LISTED  StCTIONS 


TITLE 


CERL  DISTRIBUTION 


Chief  of  Engineers 
ATTN:  DAEN-ASI-l  (?) 

ATTN:  PACN-DSE/R.  A.  MeMurrer 

ATTN:  OAEN-MPO-B 

ATTN:  PAL'N-MPO 

ATTN:  DAEN-MpQ-U 

ATTN:  DAEN-MPZ-A 

ATTN:  DAEN-MPR 

ATTN:  DAEN-ROL 

Dept  of  the  Amy 

WASH  DC  20314 

Chief  of  Engineers 
ATTN:  DAEN-PMS 
Dept  of  the  Army 
WASH  DC  20314 

for  forwarding  to: 
International  Organization 
for  Standards 
Central  Secretariat 
1,  Rue  de  Varenbe,  1211 
Geneva,  Switzerland 

US  Army  Materiel  Development 
and  Readiness  Command 
ATTN:  DRCDE-DK  (3) 

5001  Eisenhower  Ave 
Alexandria,  VA  22333 


American  National  Standards 
Inst itute 
1430  Broadway 
New  York,  NY  10018 

ANSI  X3  Committee 
C/0  CBEMA 
1828  L Street,  NW 
WASH  DC  20036 

DOD  Working  Group  on  Computer 
Documentation  Standards 
DOD/DOCN 
The  Pentagon 
WASH  DC  20301 

DOD  Working  Group  on  Computer- 
Generated  Military  Symbology 
DOD/DI SPLAY 
The  Pentagon 
WASH  DC  20301 


Federal  Information  Processing 
Standards  Coordinating  and 
Advisory  Committee 
Dept  of  Commerce 
WASH  DC  20234 


Commander 

US  Army  Electronics  Command 
ATTN:  DRSEL-TL-M/Mr.  Tenzer 
Fort  Monmouth,  NJ  07703 


Library  of  Congress 
Exchange  and  Gift  Division 
ATTN:  Federal  Documents  Section 
WASH  DC  20540 


DOD  ADP  Policy  Committee 
Assistant  Secreta'y  of  Defense 
(Comptrol ler) 

WASH  DC  20301 


Interagency  Committee  on  Automatic 
Data  Processing 
National  Bureau  of  Standards 
WASH  DC  20234 


DOD  Standardization  Area 
Computer  Aided  Design  and 
Numerical  Control 
Naval  Ship  Engineering  Center 
Hyattsvi 1 le,  MD  20782 

DOD  Standardization  Program 
For  Information  Processing 
Standards  for  Computers  ( I PSC ) 
Directorate  of  Data  Automation 
(AF/K.RAX) 

HQ,  USAF 
WASH  OC  20330 

Commander 

HQ,  XVI II  Airborne  Corps  and 
Tort  Braqq 
ATTN:  AFZA-FE-EE 
Fort  Bragg,  NC  28307 

HQ,  7th  Army  Training  Conmand 
ATTN.  AfTTG-DEH  (5) 

APO  Up w York  09114 

Commander 

HQ  HSAfRfUR  and  7th  Army 

ODCS/Engineer 

ATTN:  AfAFN-EH  (4) 

APQ  Now  York  Q9403 

Commander 

7th  Army  Combined  Arms  Training 
Center 

ATTN : AETTM-HRD-EHD 
APO  New  York  09407 

ll5  Army  Engr  Div,  Europe 
ATTN-  Technical  Library  (3) 

APO  New  York  09757 

Commander 
V Corps 

ATTN  AETVDEH 
APO  Now  York  09079 


National  Bureau  of  Standards 
Institute  for  Computer  Sciences 
and  Technology 
WASH  DC  20234 

Defense  Documentation  Center 
ATTN:  TCA  (12) 

Cameron  Station 
Alexandria,  VA  22314 


Commander 
VII  Corps 
ATTN:  AETSDFH 
APO  New  York  09154 

Commander 

21st  Support  Command 

ATTN:  AEREH 

APO  New  York  09325 

Commander 
US  Army  Berlin 
ATTN:  AEBA-EN 
APO  New  York  0974? 

Commander 

US  Army  Southern  European  Task  Torre 
ATTN:  AESE -ENG 
APO  New  York  09168 

Commander 

US  Army  Installation  Support 
Activity,  Europe 
ATTN:  AEUES-RP 
APO  New  York  09403 

U Nell  B.  Hall,  CEC.  USNR  (Code  100) 
8B4-6366 

U.S.  Navy  Public  Works  Center 
Box  6,  FPO  San  Francisco  9b651 


Lawrie,  Linda 
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1.  Electronic  data  processing  documentation.  I.  Title.  II.  Series: 

U.S.  Construction  engineering  Research  Laboratory.  Technical  report  ; E-147. 
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